Roles API

A role is the permission set a collaborator holds on a team. Subscriby seeds three on every new team, admin, manager and viewer, and a team can add its own: a support-agent who may read and answer conversations but touch nothing else, a finance role that reads payouts and analytics. Each collaborator holds exactly one role, assigned when they are invited and changed through the team members endpoints; groups layer extra permissions on top of it for several people at once.

A role's permissions is a flat array of the same ability strings a personal access token carries, so a role can be matched against a token without a second round-trip, and the ability catalog is the list to pick from. Changing a role changes what every holder may do from the next request; deleting one detaches its permissions and leaves its holders in the team with nothing beyond what their groups grant.

Roles are read across every team the caller owns or belongs to, and a role on any other team is a 404 RESOURCE_NOT_FOUND, never a 403, so existence never leaks. Every write announces itself as a role.* event.

EndpointsCopy Anchor Link

Related

Teams APITeams group creators, roles, and projects.Team Members APITeam members are the humans who collaborate inside a team: the creator who owns it and the people they invited to help run its projects.Groups APINamed permission bundles several people shareAbility CatalogEvery ability string a token can carry, what enforces it on the API and the MCP server, and how to pick the right ones when minting.role.* eventsRole create, update and delete.