Book a demo

update_role_template

Edit a role template

act entity tenant-private since 2026-10-01

Renames one of the org's own role templates, changes its description, and adds the permissions in `grant` and removes those in `revoke`. Everyone holding it holds the change at once. Shipped templates cannot be edited; clone one instead. You can edit only a template that carries nothing your own role in the org does not, and it can end up carrying only permissions your role carries. The same edit again changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: role.manage (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
role.updated
MCP tool
update_role_template
decision_set
approve, reject, edit
REST
POST https://api.containertradehq.com/v1/cap/update_role_template

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 template belongs to.
role_idtextrequired1 to 20 characters
The org's own template to edit: a clone id (RT and twelve characters).
titletextoptional1 to 80 characters
Its new name, unique within the org.
descriptiontextoptional1 to 400 characters
What it is for.
grantpermissionsoptionalunique
Permissions to add.
revokepermissionsoptionalunique
Permissions to remove.

Response

  • role_id · string · The template's id.
  • org_id · string · The org it belongs to.
  • title · string · Its name.
  • description · stringnull · What it is for.
  • cloned_from · string · The template it was cloned from.
  • modules · string[] · Its module tags.
  • permissions · string[] · The permissions it now carries.
  • clerk_role · string · The Clerk built-in role its members hold: org:admin when it carries org.admin, else org:member (TRA-963).
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "role_id": {
      "type": "string",
      "description": "The template'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 belongs to.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "Its name.",
      "x-data-class": "operational"
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "What it is for.",
      "x-data-class": "operational"
    },
    "cloned_from": {
      "type": "string",
      "description": "The template it was cloned from.",
      "x-data-class": "operational"
    },
    "modules": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Its module tags.",
      "x-data-class": "operational"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The permissions it now carries.",
      "x-data-class": "operational"
    },
    "clerk_role": {
      "type": "string",
      "description": "The Clerk built-in role its members hold: org:admin when it carries org.admin, else org:member (TRA-963).",
      "x-data-class": "operational"
    }
  },
  "required": [
    "role_id",
    "org_id",
    "title",
    "description",
    "cloned_from",
    "modules",
    "permissions",
    "clerk_role"
  ],
  "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
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates a role
  • Outbound: crosses to no counterparty

Events

Related

clone_role_template, delete_role_template, get_data_policy, set_data_policy