create_role
Create a role on a team with a permission set. The code is immutable.
Creates a role on a team. A role is what one collaborator is — everyone in a team holds exactly one. For a named bundle several people share, use create_group instead.
Subscriby seeds admin, manager and viewer on every new team; this adds your own.
Choose the code deliberately
code is unique within the team and cannot be changed afterwards —
invitations and role assignments address it. Only name, description and
the permission set stay mutable.
Growth-tier capability. On a lower tier this returns TEAM_TIER_REQUIRED and
creates 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
team_id*stringUUID of the team the role belongs to.
code*stringStable identifier, alpha-dash. Unique per team and immutable once created.
name*stringHuman-readable role name.
descriptionstringoptionalOptional description of what the role is for.
permissionsarrayoptionalPermission codes (entity:action) to grant. Omit for a role with none.
What it returns
{ "data": { "id": "d05e1a83-7c46-4f29-b613-8ae407c9d251", "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86", "code": "auditor", "name": "Auditor", "description": "Read-only access to subscriptions and payments", "permissions": ["project:view-any", "project-subscription:view-any"] }}Emits role.created.
How it fails
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks role:create.
TEAM_TIER_REQUIREDthe caller's platform tier does not include Teams.
RESOURCE_NOT_FOUNDno such team, or the caller is not a member.
VALIDATION_FAILEDcode already used on that team, malformed code, or a permission string that is not in the catalog.
How is this guide?
Last updated on