Three places to put a person in the loop
Human gates pause work, record the exact request, and resume only after a decision. Where the gate is declared determines its reach. An organization requirement always creates an approval; an agent-selected tool can instead ask the person in the conversation for a confirmation. These decisions have different answerers and deadlines. The three places to declare gates are below; an agent cannot remove an organization requirement.
| Layer | Set by | Reaches | Gates |
|---|---|---|---|
| Organization - Tool approvals on an integration | Organization admin | Every agent in the organization | Any tool, reads included |
| Agent - Approvals in the Setup | The agent's editors | This agent only | Any tool it holds |
| Flow - an approval gate or human task step | The flow's editors | That step of that flow | The work after the step |
Organization: require approval on a tool
Open an integration under Integrations, then Tool approvals in the Tools section. Switching Require approval on for a tool suspends every agent in the organization that calls it, on every call, until a person approves. The badge Approval required then follows the tool wherever it is listed.
Both this layer and the agent layer can gate a read. A read cannot change the external system, but a query shaped to pull out everything it can reach is still worth a look. What makes this layer distinct is reach and removability, not which tools it covers: it is the only one an agent's author cannot loosen. The Setup's own list is unioned with the organization's, and the agent's Approvals drawer shows the organization-mandated tools as a fixed line above the ones the author can choose.
It applies to agent turns. A flow's tool steps are governed by the flow's own gates, not by this switch.
Agent: gate a tool
Under Setup → Settings → Approvals, domain Editors and Owners pick which of an agent's tools pause for a decision. The list offers every tool the agent reaches, reads and writes alike, grouped by integration and badged Read or Write per row. Gating a read also stops that call running in parallel with its neighbours, which is the only cost the badge is there to tell you about.
In an attended conversation, a selected tool asks the person who initiated that turn for confirmation, provided it uses their own credentials or the domain's credentials. Only that person can answer, including a Viewer. Confirmations stay in the conversation and never enter the Approvals inbox.
For unattended work, work using someone else's credentials, or a tool the organization requires to be approved, the pause is an approval routed by credential authority. An organization requirement always takes precedence over the agent's confirmation setting.
Three settings live in the same drawer.
- How long a pause waits - one field per class, because the people waiting are different. In a chat defaults to 4 hours, with approvers to 72. Setting one never moves the other. The floor is a minute and the ceiling thirty days. Expiry fails the turn rather than running the call without a decision.
- An agent or flow that calls this agent may approve it too - shown under each gated tool. When another agent or flow runs this agent, that caller becomes an additional decider for the gate. The request still lands in Approvals for anyone who could always decide it, and whichever comes first wins. Off by default, per tool, because a model authorizing a model's side effect is a standing decision an agent editor makes about one specific write. See Calling other agents.
- The Setup's Delegation row sets how many questions a called agent may ask this one - related, but a question authorizes nothing and never enters Approvals.
The published Setup is what runs. Editing the list in a draft changes nothing until you publish; a test drive uses the draft.
Flow: an approval gate or a human task
A flow declares its own pauses as steps. An approval gate carries a message for the approver, a role floor (operator or higher by default), an approve outlet and a reject outlet, an option to block the run's initiator from approving their own gate, and a timeout that defaults to 24 hours. The step's role floor applies in addition to the domain's approval policy. A reject with no outlet fails the run with the rejection. A human task pauses for an Operator, Editor or Owner who meets its assignee-role floor to fill in declared fields, and their answers become step outputs.
There is no amount threshold on a gate itself. Route around it with a condition step - the Refund approval template branches on the amount and only sends larger refunds to the gate.
Who may decide
Authority follows the credentials the gated work runs on, not seniority.
- Domain-routed approvals follow the domain's approval policy: Operator or above by default. A domain Owner can set another minimum role or a list of named domain members. A nonempty list replaces that domain role floor, so a named Viewer can decide an agent approval. A Flow gate's own role floor still applies in addition to either policy.
- Your credentials marks work using a person's own sign-in or a credential they supplied on an API request. Only that person may decide it, whatever their role, while they retain domain access. Neither organization nor domain seniority overrides this identity.
- Confirmations can be answered only by the recorded initiator of the attended turn, including a Viewer. Other session participants cannot answer on their behalf.
- Human tasks require the domain approval action (Operator or above) and the step's assignee-role floor. A named Viewer on the domain's approval list does not gain this separate action.
- A gate configured to block self-approval refuses the run's initiator even at the right role.
Being allowed to view or participate in a session does not by itself grant approval authority. See the full Roles and permissions reference.
A row can also be blocked - its credential became unavailable while it waited, or the person it was routed to left the domain or was deactivated. A blocked item cannot be decided until the credential is restored; it keeps its original expiry. Cancelling a parked run or turn withdraws its approval, and the audit trail keeps why.
Support staff signed in to your workspace under a grant cannot decide approvals unless the grant is full write mode.
The inbox, and the history
Sessions → Approvals shows approvals and human tasks you may decide, with filters by type, authority and readiness, and a decision drawer with an optional comment. The same decision can be made inline in the session, where the pending call sits with its exact arguments. Confirmations appear only in their conversation. See Approvals.
History is the immutable record of what was decided: approved, rejected, timed out or withdrawn, by whom, when, with the comment or the reason. It is built from the audit trail, which is never pruned and survives the deletion of the run or conversation it came from, and it covers the domains you currently belong to.
Expiry and notification
| Layer | Default window | On expiry |
|---|---|---|
| Agent confirmation | 4 h (per agent) | The call fails and the turn ends with an error; the timeout is audited |
| Agent approval | 72 h (per agent) | The call fails, the turn ends with an error, the audit trail records the timeout |
| Flow gate | 24 h (per step) | The step fails with APPROVAL_TIMEOUT and the run times out, or the branch closes |
| Human task | 24 h (per step) | The step fails with HUMAN_TASK_TIMEOUT and the run times out |
When a gate parks work that nobody is watching - a scheduled or API-started turn, or any flow gate - the people who can decide it are emailed with the request and its deadline, and emailed again if it expires. A gate reached in a conversation someone is sitting in sends nothing; the person is already there. See Notifications.
Missed schedules need a decision too
A schedule that could not fire on time - the platform was down, or the backlog ran past two minutes - does not silently run its missed occurrences later. They are parked as a catch-up batch on the trigger's own Approvals tab, with the window they cover, how many runs they would start against the organization's queue, and the schedule and input as they were saved. Anyone who manages the domain's triggers can approve all of them, a range, or just the first, or discard the rest. The trigger must be active to approve. These never appear in the Approvals inbox, because they are a decision about a schedule rather than about a side effect.
