Book a demo

switch_org

Switch organization

act entity tenant-private since 2026-10-01

Moves the signed-in user's own session to another org: every later request acts in that org. Only an org list_switchable_orgs returns for the caller is accepted; any other is refused. Switching to the org the session is already in changes nothing. A device pinned to a unit cannot switch.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: self.act (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first
idempotency
natural
emits
org.switched
MCP tool
switch_org
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/switch_org

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 switch to: an org_id list_switchable_orgs returned.

Response

  • from_org · stringnull · The org the session was in; null for a session that had selected none.
  • to_org · string · The org the session is in now.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "from_org": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org the session was in; null for a session that had selected none.",
      "x-data-class": "operational"
    },
    "to_org": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org the session is in now.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "from_org",
    "to_org"
  ],
  "additionalProperties": false
}

Refusals

  • org_not_switchable · 422 · the org is not one list_switchable_orgs returns for the caller; an org that does not exist gets the same answer
  • session_required · 422 · the call carries no signed-in session to move
  • session_not_callers · 422 · the session the call names is not one of the caller's

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

Events

Related

None.