decide_access_review_item

Decide an access review item

act entity tenant-private since 2026-10-01

Decides one item of an open access review, and does what the decision says: keep leaves it as it is; change_role gives a member the role template role_template_id; revoke deactivates a member, revokes a guest, disables a service account (and every key of it), revokes an API key or ends a staff grant. A decision is final. You cannot decide your own row, or a service account or key you own; another admin does.

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first
idempotency: natural
emits: access_review.item_decided
MCP tool: decide_access_review_item
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/decide_access_review_item

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org the review is of.
review_id	text	required	1 to 14 characters The review.
item_id	uuid	required	UUID The item to decide.
decision	one_of	required	one of keep, change_role, revoke keep, change_role (a member's alone) or revoke.
role_template_id	text	optional	1 to 64 characters The member's new role template, for change_role.

Response

item_id · string · The item's id.
review_id · string · The review it belongs to.
kind · string · member, guest, service_account, api_key or staff_grant.
subject_id · string · Whose access: a user id, a service account id, a key id or a staff grant's id.
subject_label · value · What a reviewer reads for it: an email, or a service account's or key's name.
role · stringnull · The access it held when the review began: a role template, a key's service account, or a staff grant's level.
last_active_at · stringnull · When it was last seen acting before the review began, where known.
decision · stringnull · keep, change_role or revoke; null until decided.
new_role_template_id · stringnull · The role template a change_role decision gave the member.
decided_by · stringnull · Who decided it.
decided_at · stringnull · When it was decided.
own · boolean · Whether it is the caller's own row, which another admin decides.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The item's id.",
      "x-data-class": "operational"
    },
    "review_id": {
      "type": "string",
      "description": "The review it belongs to.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "member",
        "guest",
        "service_account",
        "api_key",
        "staff_grant"
      ],
      "description": "member, guest, service_account, api_key or staff_grant.",
      "x-data-class": "operational"
    },
    "subject_id": {
      "type": "string",
      "description": "Whose access: a user id, a service account id, a key id or a staff grant's id.",
      "x-data-class": "operational"
    },
    "subject_label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "What a reviewer reads for it: an email, or a service account's or key's name.",
      "x-data-class": "personal"
    },
    "role": {
      "type": [
        "string",
        "null"
      ],
      "description": "The access it held when the review began: a role template, a key's service account, or a staff grant's level.",
      "x-data-class": "operational"
    },
    "last_active_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was last seen acting before the review began, where known.",
      "x-data-class": "operational"
    },
    "decision": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "keep",
        "change_role",
        "revoke",
        null
      ],
      "description": "keep, change_role or revoke; null until decided.",
      "x-data-class": "operational"
    },
    "new_role_template_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The role template a change_role decision gave the member.",
      "x-data-class": "operational"
    },
    "decided_by": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who decided it.",
      "x-data-class": "operational"
    },
    "decided_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was decided.",
      "x-data-class": "operational"
    },
    "own": {
      "type": "boolean",
      "description": "Whether it is the caller's own row, which another admin decides.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "item_id",
    "review_id",
    "kind",
    "subject_id",
    "subject_label",
    "role",
    "last_active_at",
    "decision",
    "new_role_template_id",
    "decided_by",
    "decided_at",
    "own"
  ],
  "additionalProperties": false
}

Refusals

access_review_not_found · 422 · the org has no such access review
access_review_item_not_found · 422 · the review has no such item
review_closed · 422 · the review is closed; its decisions are final
own_review_item · 422 · the item is the caller's own row; another admin decides it
decision_not_available · 422 · change_role is a member's alone
role_template_required · 422 · change_role needs role_template_id
review_act_refused · 422 · the act the decision runs refused; its own code is in the message and nothing was recorded
review_act_unavailable · 422 · the act the decision runs is not available to this org yet; nothing was recorded
item_already_decided · 409 · the item was decided otherwise; a decision is final

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileD5

APIF

MCPF*

VoiceD5

PushF

OneBoxN

OutboundN

Mobile: degraded: composition
MCP: approval required
Voice: degraded: composition
OneBox: no document originates an access review
Outbound: crosses to no counterparty

Events

access_review.item_decided audit_only

approve_grant, close_access_review, create_invite_link, grant_unit_role, import_users, invite_user, list_access_reviews, resolve_identity_finding, set_member_role

get a test key

curl https://api.containertradehq.com/v1/cap/decide_access_review_item \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_id>","review_id":"<review_id>","item_id":"00000000-0000-4000-8000-000000000000","decision":"keep"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.decideAccessReviewItem({
  "org_id": "<org_id>",
  "review_id": "<review_id>",
  "item_id": "00000000-0000-4000-8000-000000000000",
  "decision": "keep"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.decide_access_review_item({
    "org_id": "<org_id>",
    "review_id": "<review_id>",
    "item_id": "00000000-0000-4000-8000-000000000000",
    "decision": "keep",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "decide_access_review_item",
    "arguments": {
      "org_id": "<org_id>",
      "review_id": "<review_id>",
      "item_id": "00000000-0000-4000-8000-000000000000",
      "decision": "keep"
    }
  }
}

MCP

decide_access_review_item · readOnlyHint false · approval required

“Call decide_access_review_item”