Book a demo

set_acting_scope

Set where my session acts

act entity tenant-private since 2026-10-01

Sets where the signed-in user's session acts: at an account they belong to, at the session's org, or at a unit of it. At account scope, landing_org_id names the entity acts land in; until one is chosen, every act is refused. An org admin can pin the session to a unit as a device, after which it acts only in that unit and cannot change scope. Moves no data and grants nothing.

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
device_session.pinned
MCP tool
set_acting_scope
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/set_acting_scope

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
scopeone_ofrequiredone of account, org, unit
account, org or unit.
account_idaccount_idoptionaltradehq-account-id
At account scope: the account. Required there, refused anywhere else.
landing_org_idorg_idoptionaltradehq-org-id; 1 to 20 characters
At account scope: the entity acts land in, one of the account's orgs.
unit_idunit_idoptionaltradehq-unit-id
At unit scope: a unit of the session's org. Required there, refused anywhere else.
pin_devicebooleanoptional
At unit scope: pin this session to the unit as a device. An org admin's act, and permanent for the session.

Response

  • level · string · Where the session acts: account, org or unit.
  • account_id · stringnull · The account: the scope's at account scope, else the session org's own; null when the org is in none.
  • account_name · stringnull · That account's name.
  • account_member · boolean · The caller is a member of that account, so the session can act at account scope.
  • org_id · stringnull · The session's org: the entity.
  • org_name · stringnull · The entity's name.
  • landing_org_id · stringnull · At account scope, the entity acts land in; null until one is chosen, and at any other level.
  • landing_org_name · stringnull · That entity's name.
  • unit_id · stringnull · At unit scope, the unit.
  • unit_name · stringnull · The unit's name.
  • device · boolean · The session is a device pinned to its unit: it acts only there and cannot change scope.
  • mode · string · The session's mode: live, or test, where it acts in the org's test twin.
  • test_mode_allowed · boolean · The caller may enter test mode: their role in the session's live org carries org.admin or api_key.read. Leaving test is open to anyone in it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "level": {
      "type": "string",
      "enum": [
        "account",
        "org",
        "unit"
      ],
      "description": "Where the session acts: account, org or unit.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "The account: the scope's at account scope, else the session org's own; null when the org is in none.",
      "x-data-class": "operational"
    },
    "account_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "That account's name.",
      "x-data-class": "operational"
    },
    "account_member": {
      "type": "boolean",
      "description": "The caller is a member of that account, so the session can act at account scope.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The session's org: the entity.",
      "x-data-class": "operational"
    },
    "org_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The entity's name.",
      "x-data-class": "operational"
    },
    "landing_org_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "At account scope, the entity acts land in; null until one is chosen, and at any other level.",
      "x-data-class": "operational"
    },
    "landing_org_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "That entity's name.",
      "x-data-class": "operational"
    },
    "unit_id": {
      "type": [
        "string",
        "null"
      ],
      "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": "At unit scope, the unit.",
      "x-data-class": "operational"
    },
    "unit_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The unit's name.",
      "x-data-class": "operational"
    },
    "device": {
      "type": "boolean",
      "description": "The session is a device pinned to its unit: it acts only there and cannot change scope.",
      "x-data-class": "operational"
    },
    "mode": {
      "type": "string",
      "enum": [
        "live",
        "test"
      ],
      "description": "The session's mode: live, or test, where it acts in the org's test twin.",
      "x-data-class": "operational"
    },
    "test_mode_allowed": {
      "type": "boolean",
      "description": "The caller may enter test mode: their role in the session's live org carries org.admin or api_key.read. Leaving test is open to anyone in it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "level",
    "account_id",
    "account_name",
    "account_member",
    "org_id",
    "org_name",
    "landing_org_id",
    "landing_org_name",
    "unit_id",
    "unit_name",
    "device",
    "mode",
    "test_mode_allowed"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

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

Events

Related

None.