Book a demo

revoke_sessions

Sign sessions out

act entity tenant-private since 2026-10-01

Signs sessions out of an org at once: one session (session_id), every session of one person (user_id), or every session in the org (all: true) except the one making this call, which the answer names. Give exactly one. The person is asked to sign in again on their next request. A member who is not an admin signs out only their own sessions. A session already signed out changes nothing.

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`); account.owner (account role owner or higher in the account of the org `org_id`); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
sessions.revoked
MCP tool
revoke_sessions
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/revoke_sessions

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 to sign sessions out of.
session_idtextoptional1 to 64 characters
One session, by the id list_sessions answers.
user_iduser_idoptionaltradehq-user-id; 1 to 20 characters
Every session of this person in the org.
allbooleanoptional
true: every session in the org except the caller's own.

Response

  • org_id · string · The org.
  • revoked · string[] · The sessions signed out.
  • excluded · stringnull · For all: the caller's own session, which stays signed in.
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"
    },
    "revoked": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The sessions signed out.",
      "x-data-class": "operational"
    },
    "excluded": {
      "type": [
        "string",
        "null"
      ],
      "description": "For all: the caller's own session, which stays signed in.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "revoked",
    "excluded"
  ],
  "additionalProperties": false
}

Refusals

  • session_not_found · 422 · the session named is not one front-door has seen in the org

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 sign-out
  • Outbound: crosses to no counterparty

Events

Related

grant_unit_role, impersonate_user, list_sessions, list_unit_access, revoke_unit_role, set_member_role