set_account_role

Set an account role

act entity tenant-private since 2026-10-01

Gives a person a role in an account, owner or member, or changes the one they hold. Only someone already in one of the account's entities can be given one, a deactivated person is neither added nor made an owner, and an account keeps at least one owner. An owner provisions the account's entities and portfolios; a member sees its entities. Org roles are not changed. Setting the role a person already holds changes nothing.

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); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first
idempotency: natural
emits: account_role.changed
MCP tool: set_account_role
decision_set: approve, reject, escalate
REST: POST https://api.containertradehq.com/v1/cap/set_account_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

name	type	required	validation
account_id	account_id	required	tradehq-account-id The account.
user_id	user_id	required	tradehq-user-id; 1 to 20 characters The person, a member of one of the account's entities.
role	one_of	required	one of owner, member owner or member.

Response

account_id · string · The account.
user_id · string · The person.
role · string · The role they now hold.
previous_role · stringnull · The role they held before; null when they held none.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "The account.",
      "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 person.",
      "x-data-class": "operational"
    },
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "member"
      ],
      "description": "The role they now hold.",
      "x-data-class": "operational"
    },
    "previous_role": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "owner",
        "member",
        null
      ],
      "description": "The role they held before; null when they held none.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "account_id",
    "user_id",
    "role",
    "previous_role"
  ],
  "additionalProperties": false
}

Refusals

last_account_owner · 422 · the change would leave the account with no owner
account_person_not_in_entity · 422 · the person is a member of none of the account's entities
user_deactivated · 422 · the person is deactivated, so they are neither added nor made an owner

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 account role change
Outbound: crosses to no counterparty

Events

account_role.changed audit_only

None.

get a test key

curl https://api.containertradehq.com/v1/cap/set_account_role \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"00000000-0000-4000-8000-000000000000","user_id":"<user_id>","role":"owner"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.setAccountRole({
  "account_id": "00000000-0000-4000-8000-000000000000",
  "user_id": "<user_id>",
  "role": "owner"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.set_account_role({
    "account_id": "00000000-0000-4000-8000-000000000000",
    "user_id": "<user_id>",
    "role": "owner",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_account_role",
    "arguments": {
      "account_id": "00000000-0000-4000-8000-000000000000",
      "user_id": "<user_id>",
      "role": "owner"
    }
  }
}

MCP

set_account_role · readOnlyHint false · approval required

“Call set_account_role”