grant_capability · Grant a capability to an org

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: keyed
emits: entitlement.granted
MCP tool: grant_capability
decision_set: approve, reject, edit, request_info
REST: POST https://api.containertradehq.com/v1/cap/grant_capability

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The live org to give it to.
capability_id	text	required	1 to 63 characters The capability, by its registry name (as list_permissions and capabilities.json name it).
kind	one_of	required	one of grant, add_on grant: given outside the tier. add_on: bought on top, only a capability sold as an add-on.
reason	text	required	1 to 500 characters Why it is given: the deal, the partner, the ticket. Kept with the grant.
expires_on	date	optional	date, YYYY-MM-DD The day it stops counting, from 00:00 UTC: YYYY-MM-DD, after today's date in UTC. Absent: it does not expire.

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
org_is_a_test_twin · 422 · a test twin has its live org's grants; grant on the live org
capability_retired · 422 · the capability is retired and no longer granted
not_an_add_on · 422 · the capability is not sold as an add-on
expiry_not_in_the_future · 422 · the expiry is not after today in UTC
capability_not_found · 422 · no capability has that name
org_has_no_type · 422 · the org has no type row, so it has no entitlements to add to
idempotency_key_reused · 409 · the Idempotency-Key already made a grant with different inputs
retry_key_mismatch · 409 · the Idempotency-Key was already used with a different request
retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
retry_key_lost · 409 · another request took over this Idempotency-Key first; nothing was applied

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

Events

entitlement.granted audit_only

revoke_capability_grant, send_feedback