Skip to main content
Some actions an automation can take are too consequential to dispatch without a human looking. Charging a card above a threshold. Sending a mass email. Granting elevated workspace access. Approval gates are how the platform pauses an agent or workflow step until a human signs off, and they are the only surface where the runtime itself owns the review queue. By the end of this page you will know what an approval is, who can decide it, what the decision is bound to, and how to model “ask before doing this” without building a queue yourself.

​
An approval, in the wild

When a step reaches a gate the runtime opens an approval record and pauses the session. The record names the action that wants to dispatch and the payload that would be sent. An operator reviews and decides.
approval.json
{
  "id":         "apr_01H...",
  "agent_id":   "agt_01H...",
  "run_id":     "run_01H...",
  "status":     "pending",
  "action":     "send_email",
  "payload":    { "to": "customers@list", "subject": "Q4 promo" },
  "created_at": "2025-11-02T01:00:10Z"
}
action and payload are not interpreted by the platform — they are the same arguments the gated step would have passed. An operator reading the record sees exactly what would have been dispatched.

​
The mental model: a typed pause

Think of an approval gate as a typed pause. The agent or workflow says “I am about to do this; I cannot proceed without permission.” The runtime records the request, stops execution, and exposes the pending decision through the Approvals API and the console. A decision unblocks the original session at the exact step that paused — not by restarting the run or by re-dispatching earlier steps. Two properties to hold:
  • The gate is bound to the exact step. A decision unblocks one action. If the run has three gated steps, each one creates its own record.
  • A denial is terminal. The run stops at the denied step. The platform does not retry the gate or try a different path; re-running the work means firing the agent or workflow again, after the underlying issue is resolved.

​
What triggers a gate

A step is gated for one of three reasons. The three reasons compose: a single step can be gated for all of them at once. The approval record carries the reason set so an operator knows what asked for the review.

​
Who can decide

Decisions are scope-gated. A token needs approvals:write to call approve or deny. The platform does not separately enforce “the decider must not be the requester” by default — that is a policy you can add at the workspace level if your compliance posture requires it. Two patterns are common:

​
Lifecycle and timeouts

Approval records walk a small state machine. Each workspace configures an approval TTL (default: 7 days). A pending record older than the TTL transitions to expired automatically and the parent run stops. Long-running approvals are a smell — if your reviewers routinely take longer than a working week, either raise the TTL or rethink whether the action belongs behind a gate at all.

​
What gets logged

Every approval and every decision lands in the workspace audit chain. The recorded fields: The audit record outlives the run; you can read the decision history for a closed approval indefinitely.

​
When to use a gate (and when not to)

Use a gate when: Don’t use a gate when: