Skip to main content

What approval flows solve

Some agent actions are too sensitive to run without a human saying yes first. File deletions, financial transfers, permission escalations, these benefit from a checkpoint before execution. theAuth supports this with a permission constraint called requireApproval. When the permission engine sees it, authorization is denied with the reason "This action requires human approval before execution". Your application catches that signal, creates an approval request, notifies a human, and retries the action after a response comes back. The flow is async. The agent does not block waiting. The human can respond minutes or hours later, within the request’s TTL.
An approval only unlocks an action when the call carries its id. A permission with requireApproval: true is still denied every time unless you pass approvalId to authorize() or policy.evaluate(). approve(), deny() and decide() refuse a request past its expiresAt and mark it expired. cleanup() marks every overdue pending request as expired.
theAuth creates the approval request and persists it. Delivering the notification to the human, email, Slack, push notification, is your application’s job. Use webhookUrl or onApprovalNeeded to hook into your existing notification stack.

How the flow works

1
Agent triggers approvalThe agent calls an action protected by requireApproval: true. Authorization is denied. Your application detects the denial reason and calls theauth.approval.request().
2
Human gets notifiedWhen you call theauth.approval.request(), theAuth persists the request and fires your webhookUrl or onApprovalNeeded handler with the request details. Your app sends an email, opens a Slack DM, or surfaces a notification in your dashboard.
3
Human approves or deniesThe human clicks a button in your UI. Your UI calls your backend, which calls theauth.approval.approve(requestId) or theauth.approval.deny(requestId).
4
Agent retriesCheck the decision with theauth.approval.get(requestId). Once the status is approved, call authorize() or policy.evaluate() again with approvalId: requestId. theAuth verifies and spends the approval and allows the call, then your application carries out the action. Pass the request ID back to the agent so it can poll or be woken up when a decision arrives.

Spending an approval

Pass approvalId on the request:
When the matched permission requires approval (or policy.evaluate would escalate for a risk tier that requires approval), theAuth checks that the request exists, is approved, belongs to this agent, has exactly this action and resource, has not expired and has not been used. It then marks the request consumed and allows the call. An approval is single use: the check and the consume are one conditional update (consumed_at IS NULL), so when two calls race with the same approvalId exactly one is allowed. Other constraints on the permission, such as timeWindow and ipAllowlist, still apply, and a call that fails them does not use up the approval. A tier that requires step_up is not satisfied by an approval. If the approval cannot be spent, the call is denied with one of these reasons: The approval is bound to a hash of the action, resource and arguments. Reserved keys such as approvalId are stripped from the arguments before hashing, and a request stored without arguments only covers a call without arguments. The canonical form is the one theauth-go hashes, so the same request has the same hash in both libraries for JSON shaped arguments (object keys sorted by UTF-8 bytes, Go’s string escaping including <, > and &, float64 number text). An argument that cannot be hashed, such as NaN, Infinity or a reference cycle, never matches an approval. An integer beyond 2^53 only matches across languages when the TypeScript side passes a bigint, because a JavaScript number has already lost its low digits. A successful spend returns allowed: true with code approval_consumed. The generic approval_invalid code is no longer returned. The allow is audited with approver_id set to the request’s respondedBy and the approval id in the row’s parameters.approvalId. Upgrading adds a nullable consumed_at column to theauth_approval_requests automatically.

Requesting and deciding

Every step writes an audit row (approval.request, approval.approve, approval.deny, approval.expire). When observability.onDecision is set, each step also emits a decision event with source: "approval": Spending the approval in authorize() emits the usual event with code approval_consumed.

ApprovalRequest fields

string
Unique identifier prefixed apr_.
string
The agent requesting approval.
string
The user who owns the agent and should receive the notification.
string
The action the agent wants to perform.
string
The resource the action targets.
Record<string, unknown> | undefined
The arguments the agent passed at the time of the call.
'pending' | 'approved' | 'denied' | 'expired'
Current state. Only pending requests can be approved or denied; approve() and deny() throw on any other status.
Date
When the request expires if no response is received. Default TTL is 5 minutes (ttl is in seconds).
Date | undefined
When the human responded.
string | undefined
Identifier of the person who approved or denied.
number
How many distinct approvers the request needs. 1 unless you asked for a quorum.
string[] | undefined
Approvers counted so far, oldest first. Only set when requiredApprovals is above 1.
Date
When the request was created.

Configuration

Pass approval config to createTheAuth:
Or use a custom handler for full control over delivery:
Both webhookUrl and onApprovalNeeded fire asynchronously (not awaited) so the request() call is not delayed by notification latency. If both are set, both fire.

The approval.pending webhook

When webhooks is configured, a new pending request also sends approval.pending to endpoints that subscribe to it. The payload carries approvalId, agentId, userId, action, resource, argumentsHash, requiredApprovals, approvalsReceived (0 for a new request), expiresAt and createdAt. It never carries the raw arguments, so fetch them with approval.get(approvalId) when your approver needs to see them. A request that needs a quorum also sends approval.vote after each approval that does not complete it. The payload carries approvalId, approverId, approvalsReceived and approvalsRequired. Use it to nudge the next approver.

How webhooks work

When webhookUrl is set, theAuth sends a POST to that URL with a JSON body:
The webhook is a plain POST with no signature header and no retries. Delivery failures are non-fatal. The request is already persisted, your app can poll listPending() as a fallback.

Code examples

Set up a permission that requires approval

Catch the denial and create a request

Approve or deny from your UI handler

List pending requests for a user

Expire stale requests

Requests that exceed their TTL are still stored with status: 'pending' until you run cleanup. Call this from a cron job:

Check the status before retrying

Quorum approvals (two person rule)

Some actions should never rest on one person’s click. A request can require several distinct approvers before it becomes approved. The default is 1, so nothing changes until you ask for more.
To set it for many requests at once, use approval.requiredApprovals for a default, or approval.quorum(request) to choose per action. An explicit requiredApprovals on request() wins. The value must be a whole number from 1 to 10. The rules for a request that needs more than one approver:
  • The requester (userId) and the agent cannot approve it, whatever allowSelfApproval says. approve() throws ApprovalQuorumError with code SELF_APPROVAL.
  • Each approver counts once. A second approval from the same person throws DUPLICATE_APPROVER. This is enforced by a primary key on theauth_approval_votes, so two parallel calls from one approver cannot both count.
  • A named approver is required (APPROVER_REQUIRED otherwise).
  • One denial ends the request. Any approver can veto.
  • Expiry covers the whole quorum. If the request expires before the last approver acts, it is expired and the earlier approvals are worth nothing.
  • Every approval writes its own approval.approve audit row with approvalsReceived, approvalsRequired and quorumComplete, so the trail shows who approved and in what order.
  • A step-up rule applies to each approver separately.
  • Until the quorum is complete the status is pending, so authorize() answers approval_pending. Once approved, the usual rules hold: one spend, bound to the exact arguments, same expiry.
Over the admin API, POST /approvals takes requiredApprovals. POST /approvals/:id/approve answers { status: "pending", approvalsReceived: 1, requiredApprovals: 2 } until the last approver, then status: "approved". A repeat approver gets 409 DUPLICATE_APPROVER and the requester gets 403 SELF_APPROVAL. The dashboard inbox shows “1 of 2 approvals” and who has approved. See Robotics and ROS 2 for a dangerous robot command example. Other storage and clients follow the same rules. The Prisma adapter has castApprovalVote (see Prisma), and the Python and Go clients take the quorum when they open a request:
POST /approvals only opens requests whose action looks like admin:<name>, owned by the signed in admin and the configured system agent. It does not open a request for another agent’s execute call, so an agent action is still opened with theauth.approval.request() in your server code.

From the command line

theauth approvals talks to the admin API over HTTP, so it works against any server that mounts adminApi. It uses the token from theauth login, or --token / THEAUTH_ADMIN_TOKEN, and the server from --server or THEAUTH_URL.
Add --json for machine output. --args '{"key":"value"}' attaches arguments to a request, and --limit caps the list (1 to 100). A 401 step-up challenge tells you to sign in again. This feature adds migration 0013 (a nullable required_approvals column and the theauth_approval_votes table). Run theauth migrate before you use it.

Requiring a fresh passkey or TOTP code

For risky actions you can require that the person approving just proved who they are. Set approval.requireAcr, approval.maxAuthAge or an approval.stepUp callback, or pass stepUp to request(). The rule is stored on the request and enforced when someone approves it. See step-up authentication.

Next steps

Permissions

Add requireApproval constraints to individual permissions.

Trust scoring

Trust levels are separate from approval. Use them in your own logic to decide which agents get requireApproval permissions.

Audit trail

Denials caused by requireApproval are written to the audit log as denied. An allow that spends an approval is audited with the approver’s id in approver_id. Creating a request (approval.request) and approving or denying it (approval.approve, approval.deny) also write audit entries.
Last modified on October 19, 2026