Book a demo

revoke_unit_role

Remove access on a unit

act entity tenant-private since 2026-10-01

Removes a member's role on one unit, and with it what that role gave them there and on every unit beneath it. Their org role and their roles on other units stay. You must administer the unit, the role must carry nothing you do not hold there, and you cannot remove your own. Removing a role that is already gone changes nothing.

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`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); org.member (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first
idempotency
natural
emits
unit_role.revoked
MCP tool
revoke_unit_role
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/revoke_unit_role

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

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose tree the unit is in.
unit_idunit_idrequiredtradehq-unit-id
The unit the role is held on.
user_iduser_idrequiredtradehq-user-id; 1 to 20 characters
Who holds it.

Response

  • org_id · string · The org.
  • unit_id · string · The unit.
  • unit_name · string · The unit's name.
  • user_id · string · Who held it.
  • role_template_id · stringnull · The template the removed grant carried; null when there was none to remove.
  • revoked · boolean · Always true: they hold no role on this unit now.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org.",
      "x-data-class": "operational"
    },
    "unit_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-unit-id",
      "description": "The unit.",
      "x-data-class": "operational"
    },
    "unit_name": {
      "type": "string",
      "description": "The unit's name.",
      "x-data-class": "operational"
    },
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who held it.",
      "x-data-class": "operational"
    },
    "role_template_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The template the removed grant carried; null when there was none to remove.",
      "x-data-class": "operational"
    },
    "revoked": {
      "type": "boolean",
      "description": "Always true: they hold no role on this unit now.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "unit_id",
    "unit_name",
    "user_id",
    "role_template_id",
    "revoked"
  ],
  "additionalProperties": false
}

Refusals

  • own_access · 422 · You can't change your own access. Another admin can.
  • unit_outside_caller · 422 · You administer {your unit} and the units beneath it. {unit} is outside it.
  • holder_above_caller · 422 · {Name}'s role on {unit} carries {permission}, which you don't hold there.
  • tree_too_large · 422 · the org's unit tree holds more units than one call reads

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

Surfaces

DesktopF
MobileD5
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a unit role
  • Outbound: crosses to no counterparty

Events

Related

grant_unit_role, impersonate_user, list_sessions, list_unit_access, revoke_sessions, set_member_role