> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Investigation

> Explain permission grants and recorded Trust Fabric decision causes within an authorized organization audience.

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.

```json theme={null}
{
  "actorKind": "person",
  "actorId": "person_123",
  "orgUnitId": "org_acme",
  "permissionKey": "audit:read",
  "status": "granted",
  "allowed": true,
  "coveringScopes": [
    { "kind": "platform" },
    { "kind": "org_unit", "orgUnitId": "org_acme" }
  ],
  "effectivePermissionKeys": ["grants:read", "policies:read", "audit:read"],
  "sources": [
    {
      "roleKey": "governance-reader",
      "roleName": "Governance reader",
      "scope": { "kind": "org_unit", "orgUnitId": "org_acme" },
      "grantedBy": "person_admin",
      "grantedAt": 1760000000000,
      "permissionKeys": ["grants:read", "policies:read", "audit:read"]
    }
  ]
}
```

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.

```json theme={null}
{
  "decision": {
    "id": "decision_456",
    "disposition": "block",
    "gateResults": [{ "gate": "permission", "errorCode": "permission_denied" }],
    "evidence": {
      "version": 1,
      "audience": { "kind": "organization", "orgUnitId": "org_acme" },
      "sourceKind": "workflow_run",
      "attribution": "recorded"
    }
  },
  "causes": [
    {
      "recordedGate": "permission",
      "recordedErrorCode": "permission_denied",
      "canonicalGateId": "permission",
      "gateLabel": "Required permission keys",
      "gateResolution": "exact",
      "causeRegistration": "registered"
    }
  ]
}
```

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.

## Related

* [Trust Fabric](https://docs.gloo.com/forge/run/trust-fabric.md) — operating model and evidence boundaries
* [Governance](https://docs.gloo.com/forge/reference/http-api/governance) — external approval and policy HTTP routes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.