Skip to main content
GET
Explain why a person or agent has or lacks a permission
The Console’s Access check: whether a person, or an agent assigned in the organization, holds one permission at one company (orgUnitId), computed by the resolver the request gate decides with. A refusal says why in words (the layer that refused, or why it cannot be told). The answer lists the scopes covering the company, every permission effective there, and the grants behind it: role, scope, date and the role’s permissions. A person or agent outside the organization’s audience, or an agent you may not read (agents:read at its home and in your credential’s scopes, never a Personal Agent, as for listGrants), is 404 resource_missing; a credential is never explained here, because its own answer is getMyAuthority. A compatibility role’s grant is left out of sources, as listGrants leaves it out; allowed and the effective permissions are unchanged. Who gave a grant, why, and the actor’s name are never returned. 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 person's or agent's id.

Minimum string length: 1

Query Parameters

orgUnitId
string
required

The company to check at.

Minimum string length: 1
actorKind
string
required

person or agent.

Minimum string length: 1
permissionKey
string
required

The permission to explain, such as audit:read.

Minimum string length: 1

Response

The explanation

data
object
required

Why a person or agent has or lacks one permission at one company, computed by the resolver the request gate decides with: the status, whether it is allowed and, when not, the reason in words, the scopes covering the company, every permission effective there, and the grants behind it (role, scope, date and the role's permissions). Who gave a grant, why, and the actor's name are never returned.

meta
object
required