Skip to main content
GET
Get your credential's own effective authority
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Every credential may read its own authority, so this operation needs no permission. The answer is computed by the same resolver, for the same actor, as the gate that decides every other request, so a permission’s effective here is exactly what that gate allows at the same place:
  • a Personal key reads its owner’s role grants, narrowed by the key’s scopes;
  • a platform key reads its own role grants, narrowed by its scopes;
  • an External App, or its companion key, reads the app’s role grants, narrowed by the credential’s scopes.
Without orgUnitId the place is the credential’s acting organization (the platform when it has none). Name an org unit to ask what the credential can do on a record homed there. orgUnitId is the only accepted parameter; an empty, repeated or unknown parameter is 400 bad_request. credential names the caller as GET /api/v2/actor does. A resolved answer lists the grants that apply at the place, each with its role, its scope in words and its dates, and one cell per catalog permission: the roles that grant it (granted), the credential’s scopes when they narrowed it away (narrowedBy), and whether it is effective. A per-credential compatibility role (one per migrated API key or External App) is never listed, in grants or in a cell’s granted, as listMyGrants leaves it out; the permissions it carries still count toward effective. atName is null when the credential’s own grants do not cover the place, so a guessed unit’s name is never revealed. Who gave a grant, why it was given, and any other person are never returned. status: "indeterminate" means the authority cannot be told and every permission is refused there, for example scopes_unresolved when the named unit cannot be placed. A credential that cannot act at all, such as a Personal key whose owner is no longer active, is refused with 401 before it can ask. To see what permissions and roles mean, read the permission catalog and the role definitions.

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 evaluate at. Absent: the credential's acting organization.

Minimum string length: 1

Response

The credential's effective authority

data
object
required

The calling credential's own effective authority at one place: credential names it as GET /api/v2/actor does, at is the place (the acting organization unless orgUnitId was given) and atName its name, or null when the credential's own grants do not cover it. A resolved answer lists the grants that apply there and, for every catalog permission, the roles that grant it, the credential's scopes when they narrowed it away (narrowedBy) and whether it is effective, which is exactly what the request gate allows there. indeterminate means it cannot be told and every permission is refused there (for example scopes_unresolved: the named unit cannot be placed). A credential that cannot act at all, such as a Personal key whose owner is no longer active, is refused with 401 before it can ask. Who gave a grant, why, and any other person are never returned.

meta
object
required