The organization's roles: built-in roles and custom roles with their permission sets.
List the organization's roles
Returns every role of the organization: the built-in roles admin, member and no_access (is_system=true) and the custom roles, each with its permission list. Each item has the shape GET /roles/{role_id} returns. From 2026-11-30 id is the role's uuid (today's subject_id) for every role, built-in roles too; a built-in role's name stays in name.
Required scope: org.role.read (Read roles).
query Parameters
includeExtra data to add to the response: assigned_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. assigned_count is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the organization's roles › Responses
OK
Create a custom role
Creates a custom role with the supplied permissions. Built-in names ("admin", "member") are reserved. Each permission must be in the catalog (see GET /v1/permissions) and assignable (not system-only).
Required scope: org.role.manage (Manage roles).
query Parameters
includeExtra data to add to the response: assigned_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. assigned_count is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a custom role › Request Body
namedescriptionpermissionsCreate a custom role › Responses
Created
Fetch one role
Returns one role with its permission list. role_id is the role's uuid (subject_id) or a built-in role's name. 404 when the organization has no role with this id. From 2026-11-30 id is the role's uuid (today's subject_id) for every role, built-in roles too; a built-in role's name stays in name.
Required scope: org.role.read (Read roles).
path Parameters
role_idRole id: a role's uuid (Role.subject_id), or a built-in role's name (admin, member, no_access).
query Parameters
includeExtra data to add to the response: assigned_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. assigned_count is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Fetch one role › Responses
OK
Delete a custom role
Removes the role. Refuses a built-in (409 ROLE_BUILTIN_IMMUTABLE), and a role an active member holds or a role setting or mail contact names (409 ROLE_IN_USE, whose details say which - reassign first). Suspended members and pending invitations still naming the role lose it.
Required scope: org.role.manage (Manage roles).
path Parameters
role_idRole id: a role's uuid (Role.subject_id), or a built-in role's name (admin, member, no_access).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a custom role › Responses
No Content
Update a custom role
Replaces the role's permission list with the supplied one. The change reflects in each member's next refresh-token call. Built-ins cannot be modified (409 ROLE_BUILTIN_IMMUTABLE).
Required scope: org.role.manage (Manage roles).
path Parameters
role_idRole id: a role's uuid (Role.subject_id), or a built-in role's name (admin, member, no_access).
query Parameters
includeExtra data to add to the response: assigned_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. assigned_count is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a custom role › Responses
OK