Skip to main content
GET
List who holds grants at a place
Returns every holder of role grants at the scopes covering one place (the platform, and the org unit you name with its ancestors), by kind (person, agent, api_key or external_app) and id, with those grants: each grant’s role, scope in words and dates. Without orgUnitId the place is the platform scope. People’s grants are included, by id: no grant carries who gave it, why, or a person’s name. Your role grants, narrowed by your credential’s scopes, must hold grants:read at your acting organization and again at the org unit you name (at a scope covering it); otherwise the call is 403 permission_denied naming grants:read, with a recorded decisionId. As for listGrants, a compatibility role’s grant, a Personal key’s retired grant and an agent you may not read are left out. meta.partial is true when the 500-grant read cap was reached or a holder could not be decided.

Paging

Pass limit for the holders per page (default 25, at most 50; a larger value is 400 too_big) and the previous page’s meta.nextCursor as cursor, with the other parameters unchanged. Holders come in kind and id order. meta.hasMore is true exactly when meta.nextCursor is set. Each page is cut from the whole answer your credential may read, so every page applies the same rules; meta.partial reports the 500-grant read cap on every page. A cursor from other parameters or another route is 400 Invalid cursor.

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

orgUnitId
string

The org unit to read at. Absent: the platform scope.

Minimum string length: 1
limit
integer
default:25

Holders per page (default 25). A value above 50 is 400 too_big; anything but a positive integer is 400 Invalid: limit.

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

The previous page's meta.nextCursor, with the other parameters unchanged; any other value is 400 Invalid cursor.

Minimum string length: 1

Response

Holders

data
object[]
required
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.