Book a demo

grant_staff_role

Grant a staff role

act entity tenant-private since 2026-10-01

Gives a member of Trade HQ's Internal org one of the four staff roles: staff_read, staff_ops, staff_provision or staff_finance. Someone who is not a member of the Internal org is refused: invite them into it first. A deactivated or anonymized user is refused. Granting a role they already hold changes nothing. Staff with staff.ops only.

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
staff_role.granted
MCP tool
grant_staff_role
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/grant_staff_role

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

nametyperequiredvalidation
user_iduser_idrequiredtradehq-user-id; 1 to 20 characters
The member of the Internal org to make staff.
role_idone_ofrequiredone of staff_read, staff_ops, staff_provision, staff_finance
The staff role to grant.

Response

  • user_id · string · The staff member.
  • role_id · string · The staff role they hold.
  • org_id · string · The Internal org it is held in.
  • granted_by · string · Who granted it.
  • granted_at · string · When it was granted.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "The staff member.",
      "x-data-class": "operational"
    },
    "role_id": {
      "type": "string",
      "enum": [
        "staff_read",
        "staff_ops",
        "staff_provision",
        "staff_finance"
      ],
      "description": "The staff role they hold.",
      "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 Internal org it is held in.",
      "x-data-class": "operational"
    },
    "granted_by": {
      "type": "string",
      "description": "Who granted it.",
      "x-data-class": "operational"
    },
    "granted_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was granted.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "user_id",
    "role_id",
    "org_id",
    "granted_by",
    "granted_at"
  ],
  "additionalProperties": false
}

Refusals

  • not_internal_member · 422 · the user is not a member of Trade HQ's Internal org; invite them into it first
  • user_anonymized · 422 · the user is anonymized, and an anonymized user holds no role
  • user_deactivated · 422 · the user is deactivated; reinstate them before making them staff

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 staff role
  • Outbound: Trade HQ's own staff; crosses to no counterparty

Events

Related

None.