list_service_accounts · List service accounts

Contract

shape: collection
authority: read
evidence: none
subscription: false
permission: any one of: staff.read (the staff role staff_read 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`); api_key.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: safe
emits: none
MCP tool: list_service_accounts
REST: POST https://api.containertradehq.com/v1/cap/list_service_accounts

Idempotency: a read: calling again changes nothing

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org whose service accounts to list.
include_disabled	boolean	optional	Also list disabled accounts. False by default.

Paginated: next next_after · page_max 1000 · walk_max 1000 · ceiling 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": {
          "service_account_id": {
            "type": "string",
            "description": "The account's id.",
            "x-data-class": "operational"
          },
          "org_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-org-id",
            "description": "The live org it belongs to.",
            "x-data-class": "operational"
          },
          "name": {
            "type": "string",
            "description": "What it is for.",
            "x-data-class": "operational"
          },
          "owner_user_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "Its primary owner; null only while it is suspended for want of one.",
            "x-data-class": "operational"
          },
          "backup_owner_user_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "Its backup owner, who takes over when the primary is deactivated; null once that has happened.",
            "x-data-class": "operational"
          },
          "role_template_id": {
            "type": "string",
            "description": "The role template it acts under: never Owner or Admin.",
            "x-data-class": "operational"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "live or test; its keys are sk_live_ or sk_test_ to match.",
            "x-data-class": "operational"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "suspended",
              "disabled",
              "expired"
            ],
            "description": "active; suspended when its last owner was deactivated, until an admin reassigns it; disabled, which is final; or expired.",
            "x-data-class": "operational"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it and every key of it stop working, unless renewed.",
            "x-data-class": "operational"
          },
          "keys": {
            "type": "integer",
            "description": "How many working keys it holds.",
            "x-data-class": "operational"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The start of the last minute any key of it was served a request; null if never.",
            "x-data-class": "operational"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was made.",
            "x-data-class": "operational"
          },
          "created_by": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "Who made it.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "service_account_id",
          "org_id",
          "name",
          "owner_user_id",
          "backup_owner_user_id",
          "role_template_id",
          "mode",
          "status",
          "expires_at",
          "keys",
          "last_used_at",
          "created_at",
          "created_by"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000
    },
    "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

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 service account
Outbound: crosses to no counterparty

Events

None emitted.

None.