grants:read. Recorded decision
causes require audit:read. All three operations require an active Forge user authorized for the
supplied orgUnitId; the selected organization must exist. A caller cannot use these operations
to cross an organization boundary. The Console Investigation page combines these operations and
requires both grants:read and audit:read.
Inspect company access
The company overview takes the selected organization,orgUnitId (for example org_acme).
The overview returns active role grants, workflow-version on-behalf-of grants, and Credentials that
cover the organization through its exact scope, an ancestor scope, or platform scope where the
population supports it. It is metadata-only and does not return secret values or mutate authority.
Each population carries independent complete, partial, or unavailable coverage. partial
with reason: "result_limit" means the shared 500-row population limit was reached. unavailable
with scope_unresolved means the organization ancestry could not be established. Consumers must
not turn a partial or unavailable empty population into a clean negative claim.
Explain an actor permission
The actor-permission explanation takes the organization (orgUnitId), the actor to investigate (actorKind and actorId), and the requested permissionKey.
actorKind accepts person, agent, api_key, or external_app, but this investigation currently admits only a person or an active agent in the selected organization’s audience. A person must resolve to the requested canonical person ID and have an active seat whose current worker assignment is covered by that organization. An agent must resolve to an active definition with a worker whose current assignment is covered by that organization. api_key, external_app, missing identities, redirected person IDs, archived agents, and actors outside the audience are rejected with Forbidden before role grants are resolved.
The explanation resolves only the selected organization, its ancestors, and the platform scope. Sibling organizations are not included. Its response is metadata-only: it returns the evaluated permission, effective permission keys, and role-grant provenance; it never returns credentials, grant records, or a way to change a grant.
- the role grants at those scopes;
- the agent ceiling, so an agent never holds an approve or administer permission;
- a personal agent’s person-held grants.
effectivePermissionKeys lists the catalog permissions the actor can actually exercise there.
A permission name the catalog does not define is never granted.
status is granted when allowed is true, and not_granted when it is not. not_granted
covers two cases:
- a clean denial: no held role includes the permission, or a layer cuts it away, such as the agent ceiling;
- an actor the gate cannot let act at all, for example a person who is not active.
scope_unresolved and resolver_overflow both fail closed: allowed is false, and sources
is empty. Do not treat either status as a normal denial.
Whenever allowed is false, reason says why in words, including for scope_unresolved and
resolver_overflow. Examples:
- “No role this person holds here includes See audit records.”
- “The auditor role grants it, but an agent may never hold Approve approvals.”
- “Can’t determine access: more role grants are held than can be read.”
- “Can’t determine access: this record’s company can’t be placed.”
"*" grants the whole catalog only to a holder who also holds platform_admin.
For anyone else it grants nothing, and the answer is not_granted.
reason is absent when the permission is granted.
Explain a decision
The decision explanation takes the same organization boundary (orgUnitId) and a Trust Fabric decision ID (id).
The response contains the authorized decision projection and one cause explanation for each recorded gate result, in recorded order. Each cause identifies the recorded gate and error code, its canonical gate identity and label when resolvable, and whether the gate and cause registrations are exact, legacy-unique, ambiguous, unknown, registered, unregistered, or absent. The response example below is abbreviated; returned decision and gate-result objects include additional required fields.
null; callers cannot distinguish those cases. A decision whose evidence scope is unresolved, unavailable, or denied is also withheld.
Related
- Trust Fabric — operating model and evidence boundaries
- Governance — external approval and policy HTTP routes

