Book a demo

set_member_role

Set a member's role

act entity tenant-private since 2026-10-01

Sets the role template a member holds in an org, which decides what they may call there, or the one a pending invitee will hold once they join. The template is a shipped one or the org's own, and you can give only what your own role carries, to someone whose current role carries nothing yours does not. An account owner holds the Owner role in every org of their account. Setting the template they already hold changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); 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
member_role.changed
MCP tool
set_member_role
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/set_member_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
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org the role is held in.
user_iduser_idrequiredtradehq-user-id; 1 to 20 characters
The member or pending invitee.
role_template_idtextrequired1 to 64 characters
A shipped role template's id, or one of the org's own.

Response

  • org_id · string · The org.
  • user_id · string · The member.
  • role_template_id · string · The template they now hold.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org.",
      "x-data-class": "operational"
    },
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "The member.",
      "x-data-class": "operational"
    },
    "role_template_id": {
      "type": "string",
      "description": "The template they now hold.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "user_id",
    "role_template_id"
  ],
  "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 a role change
  • Outbound: crosses to no counterparty

Events

Related

create_invite_link, decide_access_review_item, grant_unit_role, impersonate_user, import_users, invite_user, list_sessions, list_unit_access, resolve_identity_finding, revoke_sessions, revoke_unit_role