revoke_capability_grant · Revoke a capability grant

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency: natural
emits: entitlement.revoked
MCP tool: revoke_capability_grant
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/revoke_capability_grant

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 grant was given to.
org_grant_id	uuid	required	UUID The grant, as list_granted_capabilities names it.
reason	text	required	1 to 500 characters Why it ends. Kept with the revocation.

Response

org_grant_id · string · The grant's id.
org_id · string · The org it was given to.
capability_id · string · The capability, by its registry name.
kind · string · grant, given outside the tier, or add_on, bought on top.
status · string · active while it counts; expired past expires_at; revoked once revoked.
reason · string · Why it was given.
expires_at · stringnull · When it stops counting; null for never.
granted_by · string · Who gave it.
granted_via · string · The principal kind it came through: clerk_user, or mcp_subject for an agent.
granted_client · stringnull · The OAuth client an agent acted through; null otherwise.
granted_at · string · When it was given.
revoked_by · stringnull · Who revoked it; null while it is not revoked.
revoked_via · stringnull · The principal kind the revocation came through.
revoked_client · stringnull · The OAuth client an agent revoked it through.
revoked_at · stringnull · When it was revoked.
revoke_reason · stringnull · Why it was revoked.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "org_grant_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The grant'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 org it was given to.",
      "x-data-class": "operational"
    },
    "capability_id": {
      "type": "string",
      "description": "The capability, by its registry name.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "grant",
        "add_on"
      ],
      "description": "grant, given outside the tier, or add_on, bought on top.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "expired",
        "revoked"
      ],
      "description": "active while it counts; expired past expires_at; revoked once revoked.",
      "x-data-class": "operational"
    },
    "reason": {
      "type": "string",
      "description": "Why it was given.",
      "x-data-class": "operational"
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it stops counting; null for never.",
      "x-data-class": "operational"
    },
    "granted_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who gave it.",
      "x-data-class": "operational"
    },
    "granted_via": {
      "type": "string",
      "description": "The principal kind it came through: clerk_user, or mcp_subject for an agent.",
      "x-data-class": "operational"
    },
    "granted_client": {
      "type": [
        "string",
        "null"
      ],
      "description": "The OAuth client an agent acted through; null otherwise.",
      "x-data-class": "operational"
    },
    "granted_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was given.",
      "x-data-class": "operational"
    },
    "revoked_by": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who revoked it; null while it is not revoked.",
      "x-data-class": "operational"
    },
    "revoked_via": {
      "type": [
        "string",
        "null"
      ],
      "description": "The principal kind the revocation came through.",
      "x-data-class": "operational"
    },
    "revoked_client": {
      "type": [
        "string",
        "null"
      ],
      "description": "The OAuth client an agent revoked it through.",
      "x-data-class": "operational"
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was revoked.",
      "x-data-class": "operational"
    },
    "revoke_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why it was revoked.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_grant_id",
    "org_id",
    "capability_id",
    "kind",
    "status",
    "reason",
    "expires_at",
    "granted_by",
    "granted_via",
    "granted_client",
    "granted_at",
    "revoked_by",
    "revoked_via",
    "revoked_client",
    "revoked_at",
    "revoke_reason"
  ],
  "additionalProperties": false
}

Refusals

capability_not_released · 422 · the release-grant-capability flag is off for the caller; it may be turned on later
grant_not_found · 422 · the org has no grant with that id

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

Events

entitlement.revoked audit_only

grant_capability