Contract
- shape
- collection
- authority
- read
- evidence
- none
- subscription
- true
- permission
- any one of: org.admin (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_org_grants
- REST
- POST https://api.containertradehq.com/v1/cap/list_org_grants
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. |
| current | boolean | optional | true for only the grants waiting or active now. |
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": {
"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 customer org it is a grant to.",
"x-data-class": "operational"
},
"org_name": {
"type": [
"string",
"null"
],
"description": "That org's name.",
"x-data-class": "operational"
},
"grantee_user_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "The staff member it lets in.",
"x-data-class": "operational"
},
"grantee_name": {
"type": [
"string",
"null"
],
"description": "Their name, or their address when they have none.",
"x-data-class": "operational"
},
"grantee_email": {
"anyOf": [
{
"type": [
"string",
"null"
]
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "Their address.",
"x-data-class": "personal"
},
"level": {
"type": "string",
"enum": [
"read",
"act"
],
"description": "read: what the Read-only template carries. act: what the Admin template carries.",
"x-data-class": "operational"
},
"kind": {
"type": "string",
"enum": [
"request",
"break_glass"
],
"description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.",
"x-data-class": "operational"
},
"reason": {
"type": "string",
"description": "Why, in the requester's words.",
"x-data-class": "operational"
},
"requested_hours": {
"type": "integer",
"description": "How long it was asked for.",
"x-data-class": "operational"
},
"requested_at": {
"type": "string",
"format": "date-time",
"description": "When it was asked for.",
"x-data-class": "operational"
},
"exception_id": {
"type": [
"string",
"null"
],
"description": "The decision card the org's admins decide a request on.",
"x-data-class": "operational"
},
"decision": {
"type": [
"string",
"null"
],
"enum": [
"approved",
"rejected",
null
],
"description": "What the admin decided; null while it waits.",
"x-data-class": "operational"
},
"decided_by": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who decided it.",
"x-data-class": "operational"
},
"decided_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When.",
"x-data-class": "operational"
},
"approved_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it became active.",
"x-data-class": "operational"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it stops being active.",
"x-data-class": "operational"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it was revoked, if it was.",
"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.",
"x-data-class": "operational"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"rejected",
"revoked",
"expired"
],
"description": "pending, active, rejected, revoked or expired, as of now.",
"x-data-class": "operational"
},
"notified": {
"type": "integer",
"description": "How many of the org's admins a break-glass notice was written to.",
"x-data-class": "operational"
}
},
"required": [
"grant_id",
"org_id",
"org_name",
"grantee_user_id",
"grantee_name",
"grantee_email",
"level",
"kind",
"reason",
"requested_hours",
"requested_at",
"exception_id",
"decision",
"decided_by",
"decided_at",
"approved_at",
"expires_at",
"revoked_at",
"revoked_by",
"status",
"notified"
],
"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 staff grant
- Outbound: crosses to no counterparty
Events
None emitted.
Related
None.