Approval lifecycle
Approvals move throughpending → 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), 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 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: 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’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.
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 promote, demote, accept and the
two curator decisions; 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 asks 1 to 25 people with
your own form, getRequestedHumanTask
reads the outcome, and
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
are never returned either: a Personal key holds no roles and acts with its owner’s permissions,
which GET /api/v3/me/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).
To give or revoke a role, call giveRole or
revokeRole (
grants:manage); no API surface or
MCP operation defines a role. To invite a person with Builder and Auditor, call
inviteUser; to revoke an on-behalf-of grant, call
revokeOnBehalfOfGrant (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),reviewDueAtandfinding, theagent_ownershipcode.attestation:verified,attestedAt,expiresAtandfinding, theidentity_verificationcode.handoff: where a person repairs the agent, non-null exactly when either finding is.
assigned: false with agent_unowned.
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.
Repair a finding in the Console, or over the API with
agents:manage at the agent’s home:
assignOwner,
acknowledgeReview and
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.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.
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 and
Get a recorded decision.
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.
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 and
List a trust policy’s revisions.
Policy writes
SevenPOST 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).
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.*), agateway,environmentorworkflow_versionscope, or anagentscope withoutscopeIdgivesoutcome: "unknown"with the missing field inmissingFields. Forge never guesses it. - Withheld fields. A condition on
principal.personIdorprincipal.servicePrincipalIdreturns400. A machine credential can’t search decisions by a person’s or service principal’s identity. - Coverage. A page states
coverageaslistEvidencedoes.unavailableincludes a decision whose audience is unresolved: the page still returns what it evaluated, and isn’t proof of what the whole window holds.
historical: true. See
Simulate a trust policy.
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,
Report trust policies fired and
Report authorization denials by surface.
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 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.
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.
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 byPOST /api/v3/workflows/dispatchor from the Console are decided at their workflow’s home. A run with neither is never visible.getApprovalandlistRunApprovalsanswer404for 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 is403 permission_deniedanderror.requiredPermissionnames the first missing permission.
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
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).
The obsolete public adoption control has been removed.
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 — list pending approvals visible to the callerGET /api/v3/governance-approvals/{approvalId}— getApproval — fetch a single approval by IDGET /api/v3/governance-approval-policies— listPolicies — list approval policiesGET /api/v3/runs/{runId}/approvals— listRunApprovals — list one run’s approval decision trailGET /api/v3/governance-decisions/{decisionId}/explanation— explainGovernanceDecision — explain one recorded Trust Fabric decisionGET /api/v3/governance-decisions— listGovernanceEvidence — page recorded Trust Fabric decisionsGET /api/v3/governance-decisions/{decisionId}— getGovernanceEvidence — get one recorded Trust Fabric decisionGET /api/v3/governance-roles— listRoles — list the system role catalogGET /api/v3/governance-permission-catalog— getPermissionCatalog — read the permission catalog in wordsGET /api/v3/governance-role-definitions— listRoleDefinitions — list every role with what it containsGET /api/v3/me/authority— getMyAuthority — read your credential’s own effective authorityGET /api/v3/me/grants— listMyGrants — list your credential’s own grants at every scopeGET /api/v3/governance-permissions/{permissionKey}/enforcement-sites— listEnforcementSites — list where one permission is enforcedGET /api/v3/governance-holders— listHoldersAt — list who holds grants at a placeGET /api/v3/governance-holders/{holderId}/effective-authority— getEffectiveAuthority — read one holder’s effective authorityGET /api/v3/governance-holders/{holderId}/permission-explanation— explainActorPermission — explain why a person or agent has or lacks a permissionGET /api/v3/governance-company-access-overview— getCompanyAccessOverview — read a company’s access inventoryGET /api/v3/governance-on-behalf-of-grants— listOnBehalfOfGrants — list on-behalf-of grantsGET /api/v3/governance-grants— listGrants — page role grants held by API keys, External Apps, agents and (on request) peopleGET /api/v3/governance-agent-accountability— listAgentAccountability — page agents’ accountability findingsGET /api/v3/agents/{agentId}/accountability— getAgentAccountability — get one agent’s accountabilityGET /api/v3/governance-trust-policies— listTrustPolicies — list trust policies at their newest revisionGET /api/v3/governance-trust-policies/{trustPolicyId}/revisions— listTrustPolicyRevisions — list one trust policy’s revisionsPOST /api/v3/governance-trust-policies/simulate— simulateTrustPolicy — replay a trust policy against recorded decisions (a read carried in a body; historical only)POST /api/v3/governance-trust-policies— createTrustPolicy — create a trust policyPATCH /api/v3/governance-trust-policies/{trustPolicyId}— editTrustPolicy — edit a trust policyPOST /api/v3/governance-trust-policies/{trustPolicyId}/toggle— toggleTrustPolicy — enable or disable a trust policyDELETE /api/v3/governance-trust-policies/{trustPolicyId}— removeTrustPolicy — remove a trust policy revisionPOST /api/v3/governance-approval-policies— createApprovalPolicy — create an approval policyPATCH /api/v3/governance-approval-policies/{approvalPolicyId}— updateApprovalPolicy — update an approval policyDELETE /api/v3/governance-approval-policies/{approvalPolicyId}— removeApprovalPolicy — remove an approval policyGET /api/v3/governance-gate-deny-report— getGateDenyReport — count your organization’s blocked decisions by failed gateGET /api/v3/governance-policy-fired-report— getPolicyFiredReport — count your organization’s blocked and held decisions by trust policyGET /api/v3/governance-authz-surface-report— getAuthzSurfaceReport — count your organization’s permission denials by dispatch surfaceGET /api/v3/governance-denials-by-person-report— getDenialsByPersonReport — count your organization’s blocked decisions by person idGET /api/v3/governance-agent-access-on-behalf-of-report— getAgentAccessOnBehalfOfReport — list agent tool use on behalf of a person (Personal key only)GET /api/v3/governance-door-switch-board— getDoorSwitchBoard — read the emergency stops board (state and fixed copy only)GET /api/v3/me/work— listMyWork — list a Personal key owner’s open steps and approvalsGET /api/v3/governance-human-tasks/{humanTaskId}— getHumanTask — read one human task the owner may seeGET /api/v3/me/attention— listMyAttention — page the owner’s attention queueGET /api/v3/governance-human-task-input-files— listHumanTaskInputFiles — list a human step’s input filesGET /api/v3/governance-human-task-input-files/{fileId}/signed-url— getHumanTaskInputFileUrl — get a recorded read’s signed URL for a step input fileGET /api/v3/governance-attention-items— listAttention — page the operator attention listGET /api/v3/governance-attention-items/{subjectId}— getAttentionItem — read one attention item
human_tasks:use):
POST /api/v3/governance-requested-human-tasks— requestHumanTask — ask 1 to 25 named people for a decision or inputGET /api/v3/governance-requested-human-task-lookup— getRequestedHumanTask — read one of your asks and its outcomePOST /api/v3/governance-requested-human-tasks/withdraw— withdrawRequestedHumanTask — withdraw one of your asks
Common workflows
Pull the approval inbox; a person decides each one in Forge:Related
- Approvals — conceptual background on the approvals lifecycle
- Policies — how policies gate dispatches
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token

