Roles API

A role is the permission set a member holds on a team. Every team starts with eight: admin, project_manager, business_analyst, developer, qa_engineer, release_manager, viewer and guest, and an admin can add their own, a support_agent who may read and answer tickets but touch nothing else, a finance role that reads reports alone. Each member 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. On a project, a membership row can override the team role with a project role.

A role's permissions is a flat array of the same entity:action strings a personal access token carries, so a role can be matched against a token without a second round trip, and the ability catalogue 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 APIA team is the tenant: the container every project, role, group, token and webhook endpoint hangs off.Team Members APITeam members are the people inside a team: the owner and everyone invited to work in it, staff and client guests alike.Groups APINamed permission bundles several people shareAbility CatalogueEvery ability string a token can carry, how the catalogue mirrors the team permissions, what enforces it on the API today, and how to pick the right ones when minting.role.* eventsRole creation, edits and deletion.