Skip to main content
A role groups permission assignments for team members. Role resources include attributes.permissions, the assigned permission slugs in alphabetical order. A role with no assignments returns an empty array, []. Use a platform user access token. API keys cannot read or manage roles. A team role is visible to its active team’s members and owner, and to platform admins. A caller outside that team receives 404. Global roles are visible to every signed-in platform user.

Read a role

The response includes:
GET /api/v1/roles returns the same field on every visible role. Role creation, rename and permission-assignment responses also return the current assignments. Removing an assignment returns 204; retrieve the role again to read its updated permissions. Use these stored assignments to display or edit a role. Effective access also depends on ownership, permission bundles, active team membership, the requested resource and other access checks. Reading this array does not change who can manage the role or assign permissions. Team roles apply across the team.

Describe a role

description is nullable text up to 200 characters. You can supply it when creating a role or update it as the team’s owner or a platform admin. Global roles are managed by platform admins. System roles and the built-in Admin role remain locked.
Omitting description from a PATCH preserves it. Send null to clear it or an empty string to store an empty description. Text over 200 characters returns 422. An ordinary team member can read a visible role’s description but cannot change it.

Read the member count

member_count is the number of current active team members assigned to that role. It excludes pending invitations, removed memberships, deleted or inactive users, deleted teams and assignments belonging to a different team. A team role with no matching assignments returns 0. Global roles return null for this field; their cross-team totals are not published. Counts are computed for each response and are available wherever the role itself is visible, including the list response. member_count is read-only: supplying it in a create or update request returns 422.