Skip to main content
POST
Create Role
Requires roles:manage. An API key needs the workspaces:write scope.
Privilege escalation guard: a non-owner can only grant a permission set they themselves already hold. There’s no separate check for “creating vs. editing” — without this, roles:manage alone would let a member mint a role with every permission, including ones they don’t have.
The number of roles a workspace can hold is capped by the owner’s plan tier — the 4 seed roles count against that cap.

Path

string
required
Workspace ID.

Body

string
required
1–50 characters.
WorkspacePermission[]
required
Subset of the 21-entry catalog. Must be a subset of the caller’s own permissions unless the caller is the owner.
number
0–999, display order.

Response

Same shape as a List Roles row.

Errors