> ## 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.

# Governance

> Work the approvals queue and your own tasks, manage approval and trust policies, read roles, grants and the permission catalog, explain decisions, and report on them.

The Governance domain is the external surface of Trust Fabric — the platform's governance engine. It exposes the approvals queue (work paused awaiting human decision) and the policy catalog. External integrations use it to power approval inboxes; the decision itself is made by a person.

## Approval lifecycle

Approvals move through `pending` → `approved`, `rejected` or `canceled`. A pending approval typically blocks an agent dispatch or a workflow node; a person's decision unblocks it. An approval that nobody decides by its due date, or whose run ends, is canceled, never approved. Decisions are append-only and audited.

### Approvals are decided by a person

A person decides an approval: in the Forge Console, in Slack, by email reply, or through the API with
their own Personal key ([Deciding through the API](#deciding-through-the-api)), which decides as that
person. `POST /api/v2/governance/recordDecision` was removed (2026-10-10), and a platform API key or an
External App cannot decide. To hand a held run to a person, read its status with
[`GET /api/v3/runs/{runId}/trust-status`](https://docs.gloo.com/forge/reference/http-api/runs/getTrustStatus) and give
that person its `handoff`.
The read operations (`listApprovals`, `getApproval`, `listPolicies`,
`listRunApprovals`, `explainDecision`, `listEvidence`, `getEvidence`, `listRoles`,
`listGrants`, `listAgentAccountability`, `getAgentAccountability`, `listTrustPolicies`,
`listTrustPolicyRevisions`, `simulateTrustPolicy`,
`getGateDenyReport`, `getPolicyFiredReport`, `getAuthzSurfaceReport`, `getGatePathRegistry`) require
`grants:read`,
`policies:read` and `audit:read` together.

## Approvals and human tasks

These routes are the Forge Console **My Work** page, a task, the personal and operator Trust Fabric
attention queues, a human step's input files, and the actions that answer a task.

### Person-relative reads

`listMyWork`, `getHumanTask`, `listMyAttention`, `listHumanTaskInputFiles` and
`getHumanTaskInputFileUrl` answer "what is waiting on me". Call them with a
[Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md): each reads as the key's owner, the person who
created the key, never as anyone the request names. They require `approvals:read` (scope
`approvals:read`). A platform API key or an External App has no work of its own and gets `403 forbidden`
with `error.personRequired: true` and `requiredPermission: null`; no grant changes that.

Everything these reads say the owner may do — take a task over, open a step's files, approve or
reject an attention item — is judged on the owner's grants **narrowed to the key's scopes**, never
on the owner's full grants. A key carrying `approvals:read` alone sees every attention item
view-only and is never offered take-over. A task, step or file the owner may not see answers the
same `404` as a missing one.

### Deciding through the API

`actOnHumanTask` (claim, release, decline, withdraw), `completeHumanTask`, `reassignHumanTask` and
`attachHumanTaskOutputFile` act on a task as a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md)'s owner,
through the Forge Console's own transaction, and are recorded as done through the API (an approval's
`resolvedVia` is `api`). They need a key whose scopes reach `approvals:approve`, which no key
carries unless its owner picks it. A platform API key or an External
App gets `403` with `error.personRequired: true`.

Act, complete and attach declare no role permission: the owner's own place on the task decides, as in
the Console — someone the task asks may answer, claim or decline it, and the person who asked may
withdraw it. Reassign also needs `approvals:approve` at the task's home. Every check is judged on the
owner's grants **narrowed to the key's scopes**: a hold whose release rule needs a permission the key's
scopes do not reach is refused, even when the owner holds it through a role. An approval policy's
approver limits apply exactly as in the Console, and a refusal names the policy and the limit. An
action that needs a signed-in Console session is refused with the task's Console link. A hold that
sends outside Forge (external delivery) is approved only in the Console: its approve is refused that
way, and its reject is taken; the task's `form` shows that approve as `console_session`. A task the owner
may not see is `404`. Each write takes an `Idempotency-Key`; see
[Human task writes](https://docs.gloo.com/forge/reference/idempotency.md#human-task-writes).

### Review queues

The synthesis queue (requests awaiting review and provisional requests), held procedure drafts, judge
panel admissions and curator recommendations are group human tasks (`kind: "human_task"` in
`listMyWork`). Each asks everyone who holds the queue's permission at the platform scope now —
`synthesis:approve`, or `approvals:approve` for held procedure drafts — and is an active person with an
email. Claim, release and decline them with `actOnHumanTask`, and decide them with `completeHumanTask`
or the queue's own route. Take over is `reassignHumanTask` with `kind: "human_task"` and the owner
alone as the assignee; it needs `approvals:approve` at the platform scope.

On the queue routes ([Synthesis](https://docs.gloo.com/forge/reference/http-api/synthesis) promote, demote, accept and the
two curator decisions; [Judges](https://docs.gloo.com/forge/reference/http-api/judges) `resolveAdmission`), a Personal key
decides each item through its task as the owner: a bulk route skips an item that does not ask the owner
as `not_a_candidate` and one someone else claimed as `claimed_by_other`, and a single-item route answers
`403` and `409` for the same cases. A platform API key or an External App decides as before and closes the
item's open task.

### Operator attention

`listAttention` and `getAttentionItem` read the deployment's operator attention list, decided at the
deployment root: they require `audit:read`. A Personal key reads as its
owner, narrowed the same way. A platform API key or an External App is no person: it sees what an
operator who is not an administrator sees, every item view-only.

### Asking a person (External Apps and platform API keys)

Software can ask named people for a decision or input; it never answers a human task.
[`requestHumanTask`](https://docs.gloo.com/forge/reference/http-api/governance/requestHumanTask) asks 1 to 25 people with
your own form, [`getRequestedHumanTask`](https://docs.gloo.com/forge/reference/http-api/governance/getRequestedHumanTask)
reads the outcome, and
[`withdrawRequestedHumanTask`](https://docs.gloo.com/forge/reference/http-api/governance/withdrawRequestedHumanTask)
cancels an open ask. They take an External App's token or companion key, or a platform API key, holding
`human_tasks:use`; a token must also name it in its `scope`. The grant is checked where the people
asked are homed, so a grant at a sub-unit asks, reads and withdraws there. A Personal key acts as a person and gets
`403`. People answer in the Forge Console, Slack or email, each surface naming who asked.

Through a Personal key, an app's task is summary-only and decline-only:
`getHumanTask` and `listMyWork` show fixed copy and no form, never the app's text, and
`completeHumanTask` refuses every declared action with the task's Console link; **Not me**
(`decline`) is still taken.

## Roles and grants

`listRoles` returns the system roles of the Trust Fabric catalog: each role's key, name,
description, permission keys and fixed scope kind. Roles belong to the platform, so — as for
`listPolicies` — your role grants must also hold `grants:read` at the platform scope or the
deployment root org unit; otherwise the call is `403 permission_denied` naming `grants:read`.
Compatibility roles (one per migrated API key or External App) are never listed.

`getPermissionCatalog` and `listRoleDefinitions` need only `roles:read`: what permissions and
roles mean, never who holds them. `getPermissionCatalog` returns every permission in words, by
family and resource, with the roles that include it and how many access-control rows enforce it.
`listRoleDefinitions` returns every role, system and custom, with its catalog permissions, its
counts by family, the roles it includes and is included in, and its fixed scope kind;
`callerMayGive` is always `false`. Neither lists a per-credential compatibility role, and both
carry `meta.partial` for the 200-role read cap.

`getMyAuthority` needs no permission: any credential reads what it can do at one place (its acting
organization, or an `orgUnitId` it names), computed for the same actor and by the same resolver as
the request gate, so each permission's `effective` is exactly what the gate allows there. A Personal
key reads its owner's grants narrowed by its scopes. No grant carries who gave it or why, and the
credential's own compatibility role is not listed, as `listMyGrants` leaves it out.

`listMyGrants` also needs no permission and lists every role grant behind the calling credential,
at every scope (a Personal key: its owner's), without who gave it or why.

The Trust Fabric Access views need `grants:read`, decided again where they read:
`listHoldersAt` (who holds grants at a place), `getEffectiveAuthority` (one holder's layers, with a
give or revoke preview) and `explainActorPermission` (the Access check for a person or agent) at
the org unit you name; `getCompanyAccessOverview` (a company's role grants, delegations and
credentials) and `listOnBehalfOfGrants` (which workflow versions may act for which companies) at the
deployment root. `listEnforcementSites` needs `roles:read` and lists where one permission is
enforced. People's grants are visible by id; none of these returns who gave a grant, why, or a
person's name.

`listGrants` pages role grants in creation order and returns those held by API keys, External
Apps and agents that you may see, and people's grants when you ask (`includePersonGrants=true`, or
`actorKind=person` for people alone). A grant is returned only when your role grants hold `grants:read`
at its scope (an org-unit grant at that unit; a platform grant at the platform scope or the
deployment root), its role is not a compatibility role, and, for an agent's grant, you may read
that agent (`agents:read` at the agent's home, and your credential's scopes reach `agents:read`). People's grants are returned by the person's id,
and no grant carries who gave it, why, a name or an email.
Grants held by a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md)
are never returned either: a Personal key holds no roles and acts with its owner's permissions,
which [`GET /api/v3/me/actor`](https://docs.gloo.com/forge/reference/http-api/actor) reports with `permissionsSource: "owner"`.

A page may hold fewer than `limit` grants, even none, while `meta.hasMore` is `true`: continue
with `meta.nextCursor`; a cursor Forge did not issue is `400` `Invalid cursor`. `meta.partial` is
`true` when the page omitted a grant whose scope, or whose agent's home, could not be decided for
you (an organization that no longer resolves, or more role grants than one read can scan).

> [!NOTE]
>
> To give or revoke a role, call [giveRole](https://docs.gloo.com/forge/reference/http-api/governance/giveRole.md) or
> [revokeRole](https://docs.gloo.com/forge/reference/http-api/governance/revokeRole.md) (`grants:manage`); no API surface or
> MCP operation defines a role. To invite a person with Builder and Auditor, call
> [inviteUser](https://docs.gloo.com/forge/reference/http-api/governance/inviteUser.md); to revoke an on-behalf-of grant, call
> [revokeOnBehalfOfGrant](https://docs.gloo.com/forge/reference/http-api/governance/revokeOnBehalfOfGrant.md) (`grants:manage`
> at the platform scope).

## Agent accountability

An agent is **accountable** when it is owned by an active person, its owner review is not
overdue, and a person has attested its identity for its current definition. The Trust Fabric
checks this before an agent runs through two posture dials: `agent_ownership` (the owner and the
review) and `identity_verification` (the attestation). When a dial enforces, a run of an agent with
a finding is refused with that finding's code; while it is in shadow, the run is not refused. The accountability reads do not say whether either dial enforces.

`listAgentAccountability` pages agents oldest first and `getAgentAccountability` reads one. An
agent is returned only when your role grants hold `agents:read`, `grants:read`, `policies:read` and
`audit:read` at the agent's home org unit; PERSONAL and unhomed agents are never returned. For
`getAgentAccountability`, a missing, PERSONAL or unhomed agent, one you may not read, and one
whose home does not give you the three governance read permissions are the same `404`
`Agent not found`.

Each row carries:

* `owner`: `assigned` (true only when the owner is an active person), `reviewDueAt` and `finding`,
  the `agent_ownership` code.
* `attestation`: `verified`, `attestedAt`, `expiresAt` and `finding`, the
  `identity_verification` code.
* `handoff`: where a person repairs the agent, non-null exactly when either finding is.

No owner identity, attesting person or definition hash is returned. An owner who is no longer an
active person reads exactly like no owner: `assigned: false` with `agent_unowned`.

| Finding | Field | Meaning |
| - | - | - |
| `agent_unowned` | `owner.finding` | No owner, or the owner is not an active person. |
| `agent_review_missing` | `owner.finding` | The owner has no review due date. |
| `agent_review_overdue` | `owner.finding` | The owner review due date has passed. |
| `attestation_missing` | `attestation.finding` | No person has attested the agent's identity. |
| `definition_hash_missing` | `attestation.finding` | The agent's current definition has no hash to attest against. |
| `owner_missing` | `attestation.finding` | No owner, or the owner is not an active person. |
| `review_date_missing` | `attestation.finding` | The owner has no review due date. |
| `definition_changed` | `attestation.finding` | The definition changed after it was attested. |
| `owner_changed` | `attestation.finding` | The owner changed after the attestation. |
| `review_due` | `attestation.finding` | The owner review is due. |
| `attestation_expired` | `attestation.finding` | The attestation has expired. |
| `attestation_expiry_after_review` | `attestation.finding` | The attestation expires after the owner review is due. |

The `handoff` is `{kind: "console", decidedBy: "person", item, path, url, requiredPermission}`:
`item` is `agent_accountability:<agentId>`, `path` is
`/trust-fabric/agent-trust?agent=<encoded agentId>` (the Console agent-trust register focused on
the agent), `url` is the absolute Console URL or `null` when the deployment has no Console origin,
and `requiredPermission` is `agents:manage`.

> [!NOTE]
>
> Repair a finding in the Console, or over the API with `agents:manage` at the agent's home:
> [`assignOwner`](https://docs.gloo.com/forge/reference/http-api/agents/assignOwner),
> [`acknowledgeReview`](https://docs.gloo.com/forge/reference/http-api/agents/acknowledgeReview) and
> [`attestIdentity`](https://docs.gloo.com/forge/reference/http-api/agents/attestIdentity) (and their MCP tools). Only a
> person can attest an identity: use a Personal key; an External App or platform API key is refused.

**Why an External App's agents can start unowned.** An agent an External App creates is owned by
the app's owning person only when a person owns the app. An agent created by an
organization-owned External App has no owner, so it reads `agent_unowned` (and, until a person
attests it, `attestation_missing`) until a person assigns an owner in the Console. Forge does not
invent an owner.

**Why an app edit lapses the attestation.** A definition an External App writes is never
attested by the app. When an app's edit (`agents:write`) changes the agent's definition, the
attested definition no longer matches, so the agent reads `definition_changed` until a person
attests the new definition.

`listAgentAccountability` takes `limit` (1 to 50, default 25) and `findings=only`, which keeps
only agents with at least one finding; any other value of either is `400`. `limit` counts the
agents returned. A page holds fewer than `limit` rows, or none, either because no further agent
matches (`meta.hasMore` is `false`) or because it examined its limit of 200 agents and stopped
(`meta.hasMore` is `true`): continue with `meta.nextCursor` while `meta.hasMore` is `true`. A
cursor Forge did not issue is `400` `Invalid cursor`. `meta.partial` is `true` when the page omitted an agent
whose home could not be decided for you.

## Recorded decision explanations

`explainDecision` explains one Trust Fabric decision recorded for your credential's
acting organization, from recorded evidence only. It returns the disposition, the
recorded gate results without their messages, and a classification of each recorded
cause. Unrecognized gates and codes are reported as `unknown` or `ambiguous`.
`remediation` is always `unavailable` because no historical remediation is recorded. A decision outside your
organization, with a private fence, or from a legacy or unresolved record returns the
same `404`. With `includeCorrelation=true` it adds the recorded `runId`, `stepId` and `dispatchId`,
as `getEvidence` returns them. See [Explain a recorded decision](https://docs.gloo.com/forge/reference/http-api/governance/explainDecision.md).

## Recorded decision pages

`listEvidence` pages the decisions recorded for your credential's acting organization in a time
window, and `getEvidence` returns one by id. They follow the same rule: only decisions recorded for
exactly that organization with no private fence, and only while your actor still holds the three
permissions there. Each item adds the recorded `runId`, `stepId` and `dispatchId`, which identify the
dispatch but don't grant access to that run. A page reports truthful coverage: it counts only rows
you may see, and says `partial` or `unavailable` instead of claiming an empty window it couldn't
fully read; `unavailable` with reason `unresolved_attribution` means the scan met decisions whose
organization was never resolved, which no machine reader sees and which could be yours. Its cursor
is bound to your credential, organization, window, limit and filters, including `runId` (the run
each item's correlation names) and `gateOutcome=failed` (with `gate`: decisions where that gate ran
and failed, as the Console's "failed at a check" filter). With `includeDecisionFields=true`, each
item adds the recorded non-person fields `policyId`, `dispatchSurface`, `missingPermissionKeys`,
`blockedByGate`, `heldBy` (the holding policy's name), `retryable` and `evidence.sourceKind`. See
[List recorded decisions](https://docs.gloo.com/forge/reference/http-api/governance/listEvidence.md) and
[Get a recorded decision](https://docs.gloo.com/forge/reference/http-api/governance/getEvidence.md).

## Gate-path registry

`getGatePathRegistry` returns the registry the Console's gate explorer draws: each dispatch path's
gates in run order and its delegate, and each gate's label, description and place on every path.
It is reference data for reading recorded decisions, not an enforcement status. See
[Read the gate-path registry](https://docs.gloo.com/forge/reference/http-api/governance/getGatePathRegistry.md).

## Trust policies

Governance has two kinds of policy. **Approval policies** (`listPolicies`) decide which actions
wait for a person's approval. **Trust policies** are the Trust Fabric gate policies (Console:
Trust Fabric → Policies): a condition, an action (`block`, `require_approval`, `warn` or `log`)
and an enforcement level that the gates evaluate at dispatch.

`listTrustPolicies` lists each trust policy once, at its newest revision, enabled or not.
`listTrustPolicyRevisions` returns one policy's revision chain, oldest first. Both are decided at
the deployment root, like `listPolicies`: your role grants must hold `grants:read`,
`policies:read` and `audit:read` at the platform scope or the deployment root org unit. A
policy's author is never returned. See
[List trust policies](https://docs.gloo.com/forge/reference/http-api/governance/listTrustPolicies.md) and
[List a trust policy's revisions](https://docs.gloo.com/forge/reference/http-api/governance/listTrustPolicyRevisions.md).

### Policy writes

Seven `POST` routes change trust and approval policies the way the Console's Policies page does:
`createTrustPolicy`, `editTrustPolicy`, `toggleTrustPolicy` and `removeTrustPolicy`, and
`createApprovalPolicy`, `updateApprovalPolicy` and `removeApprovalPolicy`. Each needs
`policies:manage` at the platform scope (policies have no org-unit home, and an agent never holds the
key), runs the Console's validation (a refusal is `400` with its message), and answers the id it
wrote. A trust policy is a revision chain: only its newest revision is edited, enabled or removed
(an older one is `409`). The audit event names the credential that decided. Each takes an optional
`Idempotency-Key` (the `policy_write` rule in [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md)).

### Historical simulation

`simulateTrustPolicy` replays a candidate policy, or a stored revision, against the decisions
recorded for your credential's acting organization in a window of at most 30 days. A historical
simulation replays facts recorded on past decisions. It is not an authorization, does not predict
today's gates, and reports any fact the record does not hold as unknown.

* **Population.** The same rule as `listEvidence`: only decisions recorded for exactly your acting
  organization with no private fence, while your actor still holds the three permissions there.
  Client-reported decisions are never evaluated.
* **Unknown facts.** A decision records its agent, role and principal facts. A condition on any
  other field (`gateway.*`, `tool.*`, `run.*`), a `gateway`, `environment` or `workflow_version`
  scope, or an `agent` scope without `scopeId` gives `outcome: "unknown"` with the missing field in `missingFields`.
  Forge never guesses it.
* **Withheld fields.** A condition on `principal.personId` or `principal.servicePrincipalId`
  returns `400`. A machine credential can't search decisions by a person's or service principal's
  identity.
* **Coverage.** A page states `coverage` as `listEvidence` does. `unavailable` includes a decision
  whose audience is unresolved: the page still returns what it evaluated, and isn't proof of what
  the whole window holds.

Every page carries `historical: true`. See
[Simulate a trust policy](https://docs.gloo.com/forge/reference/http-api/governance/simulateTrustPolicy.md).

## Organization reports

Four reports count the decisions recorded for your credential's acting organization in a window
of at most 30 days: `getGateDenyReport` (blocked decisions by failed gate),
`getPolicyFiredReport` (blocked and held decisions by trust policy id),
`getAuthzSurfaceReport` (permission denials by dispatch surface) and
`getDenialsByPersonReport` (blocked decisions by person id, with no name, grant or reason). The population is the one
`listEvidence` reads, and each report states `coverage` and `resolutionRevision` the same way.
Reports cover your organization's recorded decisions; check `coverage.status` before treating
counts as complete. The window cap counts every organization's decisions in the window, so on a
busy deployment narrow the window until coverage is complete. `getGateDenyReport` with
`includePassTallies=true` also returns each gate's pass and block tallies over the same decisions,
as the Console's Gates view counts them. See
[Report gate denials](https://docs.gloo.com/forge/reference/http-api/governance/getGateDenyReport.md),
[Report trust policies fired](https://docs.gloo.com/forge/reference/http-api/governance/getPolicyFiredReport.md) and
[Report authorization denials by surface](https://docs.gloo.com/forge/reference/http-api/governance/getAuthzSurfaceReport.md).

### Agent access on behalf of a person

`getAgentAccessOnBehalfOfReport` lists which agents used which tools on behalf of a person in a
window of at most 30 days, as the Console's agent access report shows it. Only a
[Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md) acting as its owner can read it: each row's run is
checked exactly as for that person in the Console, in the org unit you name, and the key's scopes
narrow what the owner may read. The key must hold `audit:read`. Any other credential gets a
recorded `403` with `personRequired: true` and a `decisionId`. Rows leave out the Console's grant
evidence, approval ids and grant ids. See
[Report agent access on behalf of a person](https://docs.gloo.com/forge/reference/http-api/governance/getAgentAccessOnBehalfOfReport.md).

Reports that name people (denials by person, access on a person's behalf) and the
deployment-wide overview and policy effectiveness reports have no machine route: they stay in
the Forge Console.

## Emergency stops board

`getDoorSwitchBoard` reads whether each door (people, API keys, agents) is stopped, whether the
platform global stop is engaged, and the workflow publish check's mode, each with fixed copy and
when it last changed. It needs `switches:use` at the platform scope, the gate the Console's board
uses, and never returns the operator's typed reason or who changed a switch. Stopping or
resuming stays in the Console. See
[Get the emergency stops board](https://docs.gloo.com/forge/reference/http-api/governance/getDoorSwitchBoard.md).

## Row visibility

The four approval and policy reads return only records your credential may read. The route
permissions do not change — `grants:read`, `policies:read` and `audit:read`,
and the credential's scopes must reach all three — but they are also decided at each
record's home, not only at the request:

* **Approvals** (`listApprovals`, `getApproval`, `listRunApprovals`) belong to
  a workflow run. Your role grants must hold all three permissions at the run's
  home org unit, and at every company whose data the run carries. A run's home
  is its own org unit when it has one (trigger-driven launches record it), and
  otherwise its workflow's owning org unit — so runs started by
  `POST /api/v3/workflows/dispatch` or from the Console are decided at their
  workflow's home. A run with neither is never visible. `getApproval` and `listRunApprovals` answer
  `404` for a record you may not read, exactly as for one that does not exist.
* **Policies** (`listPolicies`) are the platform's catalog. Your role grants
  must hold all three permissions at the platform scope or at the deployment's
  root org unit; otherwise the call is `403 permission_denied` and
  `error.requiredPermission` names the first missing permission.

A grant at the root org unit or at the platform scope covers every homed run,
so migrated API keys, which hold a root compatibility grant, and apps not owned by an org
unit, keep seeing the approvals of runs that have a home. An app whose grants
sit only at one tenant's org unit no longer sees other tenants' approvals or
the policy catalog.

> [!WARNING]
>
> A run with no org unit of its own whose workflow has no owning org unit either
> has no home, so its approvals are not visible to any API key or External App —
> including one with a root or platform grant — and `getApproval` /
> `listRunApprovals` answer `404` for it. Answer those approvals from the Forge
> Console.

Each response item is an exact allowlist (`Approval`, `RunApprovalTrailItem`,
`Policy` in the OpenAPI document). Unset optional fields are absent, not `null`.

### Scan metadata

`listApprovals` pages. It reads both pending statuses (waiting, escalated)
together, newest first, and decides each row as it reads it, so a page holds up
to `limit` rows you may read (1 to 500, default 500) and rows you may not read
never count against it. While `meta.hasMore` is `true`, pass `meta.nextCursor`
as `cursor` for the next page; a page may be short, even empty. Rows created in
the same instant are ordered within the cursor's key, so a page boundary never
skips or repeats one. `meta.partial` is `true` when the page's scan stopped at the
4,000-row safety ceiling or the request's read budget, so it may hold fewer
rows than `limit`; its cursor still resumes after every row it read. A cursor Forge did not issue is
`400` `Invalid cursor`.

`listRunApprovals` returns up to 500 approvals of the run, oldest first, and
sets `meta.partial` when the trail reached that cap, so the list may omit rows
you may read. Page with `limit` and `cursor`; when the trail reached the cap, the last page then answers `meta.hasMore: false` with `meta.truncated: true`.

## API surface scope-map retirement

> [!NOTE]
>
> The scope map decides nothing: the API surface checks each route's catalog
> permissions against the caller's role grants, narrowed by its scopes (see
> [Permissions and scopes](https://docs.gloo.com/forge/reference/conventions.md#permissions-and-scopes)).
> The obsolete public adoption control has been removed.

The API surface derives catalog permissions from actor role grants and narrows them independently
by management-scope strings. The obsolete scope-map public control
has been retired. Original seed and unseed addresses return zero without reads,
writes, or scheduling. Authored rows remain behind a closed activation policy.

The role and autonomy-tier permission-key backfill follows the same
authored-data boundary but is a separate migration. It preserves every nonempty
permission array and treats an empty array as an authored revocation unless a
deployment-specific reviewed manifest proves the exact before and proposed
after states. Without that provenance, initialization does not schedule the
backfill and diagnostics report `needs-authority` rather than writing. These
compatibility mechanisms do not by themselves declare a deployment ready or
activate any Trust Fabric enforcement posture.

## Operations

Reads:

* `GET /api/v3/governance-approvals` — [listApprovals](https://docs.gloo.com/forge/reference/http-api/governance) — list pending approvals visible to the caller
* `GET /api/v3/governance-approvals/{approvalId}` — [getApproval](https://docs.gloo.com/forge/reference/http-api/governance) — fetch a single approval by ID
* `GET /api/v3/governance-approval-policies` — [listPolicies](https://docs.gloo.com/forge/reference/http-api/governance) — list approval policies
* `GET /api/v3/runs/{runId}/approvals` — [listRunApprovals](https://docs.gloo.com/forge/reference/http-api/governance/listRunApprovals.md) — list one run's approval decision trail
* `GET /api/v3/governance-decisions/{decisionId}/explanation` — [explainGovernanceDecision](https://docs.gloo.com/forge/reference/http-api/governance/explainDecision.md) — explain one recorded Trust Fabric decision
* `GET /api/v3/governance-decisions` — [listGovernanceEvidence](https://docs.gloo.com/forge/reference/http-api/governance/listEvidence.md) — page recorded Trust Fabric decisions
* `GET /api/v3/governance-decisions/{decisionId}` — [getGovernanceEvidence](https://docs.gloo.com/forge/reference/http-api/governance/getEvidence.md) — get one recorded Trust Fabric decision
* `GET /api/v3/governance-roles` — [listRoles](https://docs.gloo.com/forge/reference/http-api/governance/listRoles.md) — list the system role catalog
* `GET /api/v3/governance-permission-catalog` — [getPermissionCatalog](https://docs.gloo.com/forge/reference/http-api/governance/getPermissionCatalog.md) — read the permission catalog in words
* `GET /api/v3/governance-role-definitions` — [listRoleDefinitions](https://docs.gloo.com/forge/reference/http-api/governance/listRoleDefinitions.md) — list every role with what it contains
* `GET /api/v3/me/authority` — [getMyAuthority](https://docs.gloo.com/forge/reference/http-api/governance/getMyAuthority.md) — read your credential's own effective authority
* `GET /api/v3/me/grants` — [listMyGrants](https://docs.gloo.com/forge/reference/http-api/governance/listMyGrants.md) — list your credential's own grants at every scope
* `GET /api/v3/governance-permissions/{permissionKey}/enforcement-sites` — [listEnforcementSites](https://docs.gloo.com/forge/reference/http-api/governance/listEnforcementSites.md) — list where one permission is enforced
* `GET /api/v3/governance-holders` — [listHoldersAt](https://docs.gloo.com/forge/reference/http-api/governance/listHoldersAt.md) — list who holds grants at a place
* `GET /api/v3/governance-holders/{holderId}/effective-authority` — [getEffectiveAuthority](https://docs.gloo.com/forge/reference/http-api/governance/getEffectiveAuthority.md) — read one holder's effective authority
* `GET /api/v3/governance-holders/{holderId}/permission-explanation` — [explainActorPermission](https://docs.gloo.com/forge/reference/http-api/governance/explainActorPermission.md) — explain why a person or agent has or lacks a permission
* `GET /api/v3/governance-company-access-overview` — [getCompanyAccessOverview](https://docs.gloo.com/forge/reference/http-api/governance/getCompanyAccessOverview.md) — read a company's access inventory
* `GET /api/v3/governance-on-behalf-of-grants` — [listOnBehalfOfGrants](https://docs.gloo.com/forge/reference/http-api/governance/listOnBehalfOfGrants.md) — list on-behalf-of grants
* `GET /api/v3/governance-grants` — [listGrants](https://docs.gloo.com/forge/reference/http-api/governance/listGrants.md) — page role grants held by API keys, External Apps, agents and (on request) people
* `GET /api/v3/governance-agent-accountability` — [listAgentAccountability](https://docs.gloo.com/forge/reference/http-api/governance/listAgentAccountability.md) — page agents' accountability findings
* `GET /api/v3/agents/{agentId}/accountability` — [getAgentAccountability](https://docs.gloo.com/forge/reference/http-api/governance/getAgentAccountability.md) — get one agent's accountability
* `GET /api/v3/governance-trust-policies` — [listTrustPolicies](https://docs.gloo.com/forge/reference/http-api/governance/listTrustPolicies.md) — list trust policies at their newest revision
* `GET /api/v3/governance-trust-policies/{trustPolicyId}/revisions` — [listTrustPolicyRevisions](https://docs.gloo.com/forge/reference/http-api/governance/listTrustPolicyRevisions.md) — list one trust policy's revisions
* `POST /api/v3/governance-trust-policies/simulate` — [simulateTrustPolicy](https://docs.gloo.com/forge/reference/http-api/governance/simulateTrustPolicy.md) — replay a trust policy against recorded decisions (a read carried in a body; historical only)
* `POST /api/v3/governance-trust-policies` — [createTrustPolicy](https://docs.gloo.com/forge/reference/http-api/governance/createTrustPolicy.md) — create a trust policy
* `PATCH /api/v3/governance-trust-policies/{trustPolicyId}` — [editTrustPolicy](https://docs.gloo.com/forge/reference/http-api/governance/editTrustPolicy.md) — edit a trust policy
* `POST /api/v3/governance-trust-policies/{trustPolicyId}/toggle` — [toggleTrustPolicy](https://docs.gloo.com/forge/reference/http-api/governance/toggleTrustPolicy.md) — enable or disable a trust policy
* `DELETE /api/v3/governance-trust-policies/{trustPolicyId}` — [removeTrustPolicy](https://docs.gloo.com/forge/reference/http-api/governance/removeTrustPolicy.md) — remove a trust policy revision
* `POST /api/v3/governance-approval-policies` — [createApprovalPolicy](https://docs.gloo.com/forge/reference/http-api/governance/createApprovalPolicy.md) — create an approval policy
* `PATCH /api/v3/governance-approval-policies/{approvalPolicyId}` — [updateApprovalPolicy](https://docs.gloo.com/forge/reference/http-api/governance/updateApprovalPolicy.md) — update an approval policy
* `DELETE /api/v3/governance-approval-policies/{approvalPolicyId}` — [removeApprovalPolicy](https://docs.gloo.com/forge/reference/http-api/governance/removeApprovalPolicy.md) — remove an approval policy
* `GET /api/v3/governance-gate-deny-report` — [getGateDenyReport](https://docs.gloo.com/forge/reference/http-api/governance/getGateDenyReport.md) — count your organization's blocked decisions by failed gate
* `GET /api/v3/governance-policy-fired-report` — [getPolicyFiredReport](https://docs.gloo.com/forge/reference/http-api/governance/getPolicyFiredReport.md) — count your organization's blocked and held decisions by trust policy
* `GET /api/v3/governance-authz-surface-report` — [getAuthzSurfaceReport](https://docs.gloo.com/forge/reference/http-api/governance/getAuthzSurfaceReport.md) — count your organization's permission denials by dispatch surface
* `GET /api/v3/governance-denials-by-person-report` — [getDenialsByPersonReport](https://docs.gloo.com/forge/reference/http-api/governance/getDenialsByPersonReport.md) — count your organization's blocked decisions by person id
* `GET /api/v3/governance-agent-access-on-behalf-of-report` — [getAgentAccessOnBehalfOfReport](https://docs.gloo.com/forge/reference/http-api/governance/getAgentAccessOnBehalfOfReport.md) — list agent tool use on behalf of a person (Personal key only)
* `GET /api/v3/governance-door-switch-board` — [getDoorSwitchBoard](https://docs.gloo.com/forge/reference/http-api/governance/getDoorSwitchBoard.md) — read the emergency stops board (state and fixed copy only)
* `GET /api/v3/me/work` — [listMyWork](https://docs.gloo.com/forge/reference/http-api/governance/listMyWork.md) — list a Personal key owner's open steps and approvals
* `GET /api/v3/governance-human-tasks/{humanTaskId}` — [getHumanTask](https://docs.gloo.com/forge/reference/http-api/governance/getHumanTask.md) — read one human task the owner may see
* `GET /api/v3/me/attention` — [listMyAttention](https://docs.gloo.com/forge/reference/http-api/governance/listMyAttention.md) — page the owner's attention queue
* `GET /api/v3/governance-human-task-input-files` — [listHumanTaskInputFiles](https://docs.gloo.com/forge/reference/http-api/governance/listHumanTaskInputFiles.md) — list a human step's input files
* `GET /api/v3/governance-human-task-input-files/{fileId}/signed-url` — [getHumanTaskInputFileUrl](https://docs.gloo.com/forge/reference/http-api/governance/getHumanTaskInputFileUrl.md) — get a recorded read's signed URL for a step input file
* `GET /api/v3/governance-attention-items` — [listAttention](https://docs.gloo.com/forge/reference/http-api/governance/listAttention.md) — page the operator attention list
* `GET /api/v3/governance-attention-items/{subjectId}` — [getAttentionItem](https://docs.gloo.com/forge/reference/http-api/governance/getAttentionItem.md) — read one attention item

Asking a person (External Apps and platform API keys, `human_tasks:use`):

* `POST /api/v3/governance-requested-human-tasks` — [requestHumanTask](https://docs.gloo.com/forge/reference/http-api/governance/requestHumanTask.md) — ask 1 to 25 named people for a decision or input
* `GET /api/v3/governance-requested-human-task-lookup` — [getRequestedHumanTask](https://docs.gloo.com/forge/reference/http-api/governance/getRequestedHumanTask.md) — read one of your asks and its outcome
* `POST /api/v3/governance-requested-human-tasks/withdraw` — [withdrawRequestedHumanTask](https://docs.gloo.com/forge/reference/http-api/governance/withdrawRequestedHumanTask.md) — withdraw one of your asks

## Common workflows

Pull the approval inbox; a person decides each one in Forge:

```bash theme={null}
curl "$FORGE_BASE/api/v3/governance-approvals" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Approvals](https://docs.gloo.com/forge/run/approvals-and-hitl.md) — conceptual background on the approvals lifecycle
* [Policies](https://docs.gloo.com/forge/run/approvals-and-hitl.md) — how policies gate dispatches
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


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