Book a demo

get_acting_scope

Get where my session acts

read entity tenant-private since 2026-10-01

Answers where the signed-in user's session acts: at an account, an org or a unit, with each one's name. At account scope it names the entity acts land in (null until one is chosen). It says whether the session is a device pinned to its unit, whether it is in live or test mode, and whether the caller may enter test mode. Changing it is set_acting_scope.

Contract

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

Idempotency: a read: calling again changes nothing

Inputs

No inputs.

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
VoiceF
PushN
OneBoxN
OutboundN
  • Push: emits nothing
  • OneBox: no document originates a scope
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.