Book a demo

list_permissions

List permissions

read collection tenant-private since 2026-10-01

Lists the permission catalog: every permission a capability declares, with what it lets someone do, where it is held, whether a role template may carry it and whether such a role may be given on a unit or only on the whole org, the capabilities it admits to, and whether your role in the given org carries it.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: org.member (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_permissions
REST
POST https://api.containertradehq.com/v1/cap/list_permissions

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org to read `held` against.
scopeone_ofoptionalone of staff, account, org, self, seat, share, signed_in, public
Only permissions held at this scope: staff, account, org, self, seat, signed_in or public.

Paginated: next next_after · ceiling not_declared

Response

  • items · object[]
  • next_after · stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The permission, e.g. org.admin.",
            "x-data-class": "operational"
          },
          "description": {
            "type": "string",
            "description": "What holding it lets someone do.",
            "x-data-class": "operational"
          },
          "scope": {
            "type": "string",
            "enum": [
              "staff",
              "account",
              "org",
              "self",
              "seat",
              "share",
              "signed_in",
              "public"
            ],
            "description": "Where it is held.",
            "x-data-class": "operational"
          },
          "role_bindable": {
            "type": "boolean",
            "description": "Whether a role template may carry it. Staff and account permissions are not.",
            "x-data-class": "operational"
          },
          "given_on": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "unit",
              "org",
              null
            ],
            "description": "Where a role carrying it may be given (TRA-473): unit, on a unit and everything beneath it, or org, on the whole organization only. A role with any org permission cannot be given on a unit. Null when no role carries it.",
            "x-data-class": "operational"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The capabilities it admits to, by name.",
            "x-data-class": "operational"
          },
          "capability_titles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Each admitted capability's title, in plain words, in the same order as capabilities.",
            "x-data-class": "operational"
          },
          "held": {
            "type": "boolean",
            "description": "Whether your role template in the org carries it.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "name",
          "description",
          "scope",
          "role_bindable",
          "given_on",
          "capabilities",
          "capability_titles",
          "held"
        ],
        "additionalProperties": false
      }
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "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
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a permission
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.