Book a demo

clone_role_template

Clone a role template

act entity tenant-private since 2026-10-01

Makes the org's own copy of a role template, shipped or one of the org's clones, under a new title, adding the permissions in `grant` and removing those in `revoke`. The copy can carry only permissions your own role in the org carries. Shipped templates never change. Send an Idempotency-Key header: a retry with the same key and inputs returns the same copy and creates 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`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
keyed
emits
role.cloned
MCP tool
clone_role_template
decision_set
approve, reject, edit
REST
POST https://api.containertradehq.com/v1/cap/clone_role_template

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org the copy belongs to.
sourcetextrequired1 to 20 characters
The template to copy: a shipped id such as read_only, or one of the org's clone ids.
titletextrequired1 to 80 characters
The copy's name, unique within the org.
descriptiontextoptional1 to 400 characters
What the copy is for. Defaults to the source's description.
grantpermissionsoptionalunique
Permissions to add to the source's.
revokepermissionsoptionalunique
Permissions to remove from the source's.

Response

  • role_id · string · The copy's id.
  • org_id · string · The org it belongs to.
  • title · string · Its name.
  • cloned_from · string · The source template.
  • modules · string[] · The module tags, the source's.
  • permissions · string[] · The permissions the copy carries.
  • clerk_role · string · The Clerk built-in role its members hold: org:admin when the copy carries org.admin, else org:member (TRA-963).
  • created_by · string · Who made it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "role_id": {
      "type": "string",
      "description": "The copy'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"
    },
    "cloned_from": {
      "type": "string",
      "description": "The source template.",
      "x-data-class": "operational"
    },
    "modules": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The module tags, the source's.",
      "x-data-class": "operational"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The permissions the copy carries.",
      "x-data-class": "operational"
    },
    "clerk_role": {
      "type": "string",
      "description": "The Clerk built-in role its members hold: org:admin when the copy carries org.admin, else org:member (TRA-963).",
      "x-data-class": "operational"
    },
    "created_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who made it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "role_id",
    "org_id",
    "title",
    "cloned_from",
    "modules",
    "permissions",
    "clerk_role",
    "created_by"
  ],
  "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

update_role_template