update_role

Purpose

Renames a role, changes its description, or replaces the permissions it grants. code is immutable, so a rename never breaks an assignment.

Permissions replace, they do not merge

Sending permissions sets the role's permissions to exactly that list. Omit the key entirely to leave the existing set untouched while changing only the name — sending an empty array strips every permission from everyone holding the role.

Growth-tier capability. On a lower tier this returns TEAM_TIER_REQUIRED and changes nothing.

Required ability

role:update

Input schema

{
  "type": "object",
  "properties": {
    "role_id": {
      "type": "string",
      "description": "UUID of the role to update."
    },
    "name": {
      "type": "string",
      "description": "New role name. Omit to keep the current one."
    },
    "description": {
      "type": "string",
      "description": "New description. Omit to keep the current one."
    },
    "permissions": {
      "type": "array",
      "description": "Complete replacement permission set. Omit to leave permissions untouched."
    }
  },
  "required": ["role_id"]
}

Output shape

{
  "data": {
    "id": "d05e1a83-7c46-4f29-b613-8ae407c9d251",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "code": "auditor",
    "name": "Auditor & Finance",
    "description": "Read-only access to subscriptions and payments",
    "permissions": ["project:view-any", "project-subscription:view-any"]
  }
}

Emits role.updated.

Example prompts

"Give the auditor role access to the transaction breakdown as well."

"Rename the auditor role to Finance without changing what it can do."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks role:update.
TEAM_TIER_REQUIRED — the caller's platform tier does not include Teams.
RESOURCE_NOT_FOUND — no such role in any team the caller belongs to.
VALIDATION_FAILED — a permission string that is not in the catalog.

create_role
delete_role
list_roles — read the current permission set before replacing it.
Roles API