revoke_api_key · Revoke an API key · Container Trade HQ API

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: natural
emits: api_key.revoked
MCP tool: revoke_api_key
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/revoke_api_key

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

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org the key belongs to.
key_id	text	required	1 to 12 characters The key's id (its public part, as list_api_keys shows it).

Response

key_id · string · The key's id, its public part.
org_id · string · The live org it was issued on.
name · string · What it is for.
service_account_id · stringnull · The service account that owns the key and that it acts as (TRA-493); null only for a BK_ key the core issued.
kind · string · sk for a key this plane issued, legacy for a BK_ key.
mode · string · live, or test for a key that reaches the test twin.
status · string · active; expiring when it has an expiry still ahead, as a rotated key does in its overlap; expired; or revoked.
display · string · The key's prefix and id, safe to show anywhere. Never the secret.
created_at · string · When it was issued.
created_by · stringnull · Who issued it.
expires_at · stringnull · When it stops working, if it does.
revoked_at · stringnull · When it was revoked.
api_version · stringnull · The API version it is pinned to; null for a BK_ key, which follows the current version.
requests_per_minute · integernull · Its per-minute limit, or null for none.
requests_per_day · integernull · Its per-day limit, or null for none.
rotated_from · stringnull · The key it succeeded.
rotated_to · stringnull · The key that succeeded it.
grants · string[] · What the key was granted (TRA-619), in name order: the permissions it may use, each only while its service account's role template carries it. Empty for a key granted nothing and for a BK_ key.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "key_id": {
      "type": "string",
      "description": "The key's id, its public part.",
      "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 was issued on.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "What it is for.",
      "x-data-class": "operational"
    },
    "service_account_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The service account that owns the key and that it acts as (TRA-493); null only for a BK_ key the core issued.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "sk",
        "legacy"
      ],
      "description": "sk for a key this plane issued, legacy for a BK_ key.",
      "x-data-class": "operational"
    },
    "mode": {
      "type": "string",
      "enum": [
        "live",
        "test"
      ],
      "description": "live, or test for a key that reaches the test twin.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "expiring",
        "expired",
        "revoked"
      ],
      "description": "active; expiring when it has an expiry still ahead, as a rotated key does in its overlap; expired; or revoked.",
      "x-data-class": "operational"
    },
    "display": {
      "type": "string",
      "description": "The key's prefix and id, safe to show anywhere. Never the secret.",
      "x-data-class": "operational"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was issued.",
      "x-data-class": "operational"
    },
    "created_by": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who issued it.",
      "x-data-class": "operational"
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it stops working, if it does.",
      "x-data-class": "operational"
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was revoked.",
      "x-data-class": "operational"
    },
    "api_version": {
      "type": [
        "string",
        "null"
      ],
      "description": "The API version it is pinned to; null for a BK_ key, which follows the current version.",
      "x-data-class": "operational"
    },
    "requests_per_minute": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Its per-minute limit, or null for none.",
      "x-data-class": "operational"
    },
    "requests_per_day": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Its per-day limit, or null for none.",
      "x-data-class": "operational"
    },
    "rotated_from": {
      "type": [
        "string",
        "null"
      ],
      "description": "The key it succeeded.",
      "x-data-class": "operational"
    },
    "rotated_to": {
      "type": [
        "string",
        "null"
      ],
      "description": "The key that succeeded it.",
      "x-data-class": "operational"
    },
    "grants": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What the key was granted (TRA-619), in name order: the permissions it may use, each only while its service account's role template carries it. Empty for a key granted nothing and for a BK_ key.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "key_id",
    "org_id",
    "name",
    "service_account_id",
    "kind",
    "mode",
    "status",
    "display",
    "created_at",
    "created_by",
    "expires_at",
    "revoked_at",
    "api_version",
    "requests_per_minute",
    "requests_per_day",
    "rotated_from",
    "rotated_to",
    "grants"
  ],
  "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 an API key
Outbound: crosses to no counterparty

Events

api_key.revoked audit_only

get_api_usage, rotate_api_key, set_api_key_limits, set_api_key_version