Skip to main content
GET
Get a holder's effective authority
Returns what one holder (actorKind and actorId) can do at one place, computed by the resolver the request gate decides with. Each catalog permission lists the roles that grant it, the scopes that narrowed it away (narrowedBy), the cap that stops it (cappedBy: an agent ceiling, or the kind of principal the holder acts for) and whether it is effective. previewGive and previewRevoke answer as if that role were given or revoked there, as the Console’s holder view previews it. An External App holder is evaluated without a credential’s scopes; the credential’s own answer is getMyAuthority. Who gave a grant, why, and the identity of a principal in a cap are never returned. As for listGrants, an agent holder is answered only when you may read that agent (agents:read at its home and in your credential’s scopes, never a Personal Agent); otherwise the call is 404 resource_missing. A compatibility role’s grant is left out of grants and of each permission’s roles, as listGrants leaves it out; effective is unchanged. 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.

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.

Path Parameters

holderId
string
required

The holder's id.

Minimum string length: 1

Query Parameters

actorKind
string
required

person, agent, api_key or external_app.

Minimum string length: 1
orgUnitId
string

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

Minimum string length: 1
previewGive
string

A role key to preview giving at the place.

Minimum string length: 1
previewRevoke
string

A role key to preview revoking at the place.

Minimum string length: 1

Response

The holder's effective authority

data
object
required

One holder's effective authority at one place, computed by the resolver the request gate decides with. For every catalog permission: the roles that grant it, the scopes that narrowed it away (narrowedBy), the cap that stops it (cappedBy: an agent ceiling, or the kind of principal the holder acts for) and whether it is effective. An External App holder is evaluated without a credential's scopes; the credential's own answer is getMyAuthority. Who gave a grant, why, and any person's identity in a cap are never returned.

meta
object
required