update_role
Rename a role or replace its permission set. The code stays fixed.
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.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
role_id*stringUUID of the role to update.
namestringoptionalNew role name. Omit to keep the current one.
descriptionstringoptionalNew description. Omit to keep the current one.
permissionsarrayoptionalComplete replacement permission set. Omit to leave permissions untouched.
What it returns
{ "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.
How it fails
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks role:update.
TEAM_TIER_REQUIREDthe caller's platform tier does not include Teams.
RESOURCE_NOT_FOUNDno such role in any team the caller belongs to.
VALIDATION_FAILEDa permission string that is not in the catalog.
How is this guide?
Last updated on