Roles

AdminUpdated Sep 11, 2026

Backend API — secret key (Authorization: Bearer sk_…).

5 routes. Each row is one endpoint with its explanation, required scope, and whether it honours the Idempotency-Key header.

Method & path	Scope	Explanation
`GET /v1/roles`	`organizations:read`	List roles with their permissions and how many members hold each.
`POST /v1/roles`	`organizations:write`	Create a custom role. Keys are namespaced and sys_ is reserved.
`PATCH /v1/roles/:id`	`organizations:write`	Relabel a role. The key is immutable once published.
`PUT /v1/roles/:id/permissions`	`organizations:write`	Replace a role permission set. System roles are fixed.
`DELETE /v1/roles/:id`	`organizations:write`	Delete an unused custom role. A role members hold returns ROLE_IN_USE.

Was this page helpful?