Skip to main content
GET
List role definitions
Role definitions are reference data: what roles contain, never who holds them. A credential whose role grants, narrowed by its scopes, hold roles:read at its acting organization reads every role; otherwise the call is 403 permission_denied with error.requiredPermission: "roles:read". The operation takes only limit and cursor, and roles come in the Console’s order. Each role is computed from its stored permission list:
  • permissions lists catalog keys only; anything else stored is in unrecognizedPermissions, never expanded.
  • familyCounts counts its permissions by family.
  • includes names the roles whose every permission this role holds; includedIn names the reverse.
  • fixedScopeKind is the only scope kind the role may be given at, or null when either.
  • compatibility: true marks a named legacy compatibility role.
  • callerMayGive is always false: this read does not evaluate the giving ceiling. giveRole decides it for the calling credential and lists each refusal. The field keeps the shape the Console reads.
Per-credential compatibility roles (one per API key or External App) are never listed, not even inside includes or includedIn. Page with limit and cursor; meta.partial: true means the role read reached its 200-role cap, and the last page then answers meta.hasMore: false with meta.truncated: true. listRoles is narrower: it lists only the system roles, without containment, and needs grants:read, policies:read and audit:read. To give or revoke a role, call giveRole or revokeRole, which need grants:manage.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

limit
integer

The list is bounded: at most 500 items, the role catalog's maximum: creating a role past it is refused (invalid_state). Every answer is the whole list, so meta.hasMore is false. limit (1 to 1000) does not cut it.

Required range: 1 <= x <= 1000
cursor
string

A bounded list issues no cursor: meta.nextCursor is always null, and any cursor is 400.

Minimum string length: 1

Response

Role definitions

data
object[]
required
Maximum array length: 500
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.