Book a demo

revoke_guest

Revoke a guest's access

act entity controlled-share since 2026-10-01

Ends a guest's access to the org: their guest membership and the Counterparty seat it carried go, so they no longer read any document their party is seated on in the org, and their pending invitation is withdrawn. The guest's record stays, listed as revoked. Revoking a revoked guest answers the first revocation. Someone who is not a guest of the org is refused not_a_guest.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
guest.revoked
MCP tool
revoke_guest
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/revoke_guest

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 the guest is a guest of.
user_iduser_idrequiredtradehq-user-id; 1 to 20 characters
The guest, as list_guests names them.

Response

  • user_id · string · The guest.
  • org_id · string · The org they were a guest of.
  • party_id · string · The party they were.
  • seat · string · The seat they held.
  • revoked_at · string · When their access ended.
  • revoked_by · string · Who ended it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "The guest.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org they were a guest of.",
      "x-data-class": "operational"
    },
    "party_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 party they were.",
      "x-data-class": "operational"
    },
    "seat": {
      "type": "string",
      "enum": [
        "lessee",
        "seller"
      ],
      "description": "The seat they held.",
      "x-data-class": "operational"
    },
    "revoked_at": {
      "type": "string",
      "format": "date-time",
      "description": "When their access ended.",
      "x-data-class": "operational"
    },
    "revoked_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who ended it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "user_id",
    "org_id",
    "party_id",
    "seat",
    "revoked_at",
    "revoked_by"
  ],
  "additionalProperties": false
}

Refusals

  • not_a_guest · 422 · the user is not and never was a guest of the org, or is a member of it under a member template

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

Surfaces

DesktopF
MobileF
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a revocation
  • Outbound: a revocation sends nothing to the guest

Events

Related

None.