Skip to main content
Trust Investigation is an operator-facing, read-only Console surface for inspecting company access, explaining why an eligible person or agent has a permission, and identifying which recorded gates caused a decision. It is not mounted as an HTTP API route. Use the Forge Console Investigation page. The company overview and actor-permission explanation require 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 answer is the one the permission gates decide on. Every layer counts:
  • 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.”
A role that stores "*" 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.
This is also metadata-only. The operation projects only the decision fields authorized for the caller and never returns private component fields or receipt data. A missing decision and a decision outside the caller’s authorized evidence population both return null; callers cannot distinguish those cases. A decision whose evidence scope is unresolved, unavailable, or denied is also withheld.
  • Trust Fabric — operating model and evidence boundaries
  • Governance — external approval and policy HTTP routes