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 calledrequireApproval. 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.
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
PassapprovalId on the request:
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
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
Current state. Only
pending requests can be approved or denied; approve() and deny() throw on any other status.When the request expires if no response is received. Default TTL is 5 minutes (
ttl is in seconds).Approvers counted so far, oldest first. Only set when
requiredApprovals is above 1.Configuration
Pass approval config tocreateTheAuth:
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
Whenwebhooks 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
WhenwebhookUrl is set, theAuth sends a POST to that URL with a JSON body:
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 withstatus: '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 becomesapproved. The default is 1, so nothing changes until you ask for more.
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, whateverallowSelfApprovalsays.approve()throwsApprovalQuorumErrorwith codeSELF_APPROVAL. - Each approver counts once. A second approval from the same person throws
DUPLICATE_APPROVER. This is enforced by a primary key ontheauth_approval_votes, so two parallel calls from one approver cannot both count. - A named approver is required (
APPROVER_REQUIREDotherwise). - 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
expiredand the earlier approvals are worth nothing. - Every approval writes its own
approval.approveaudit row withapprovalsReceived,approvalsRequiredandquorumComplete, 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, soauthorize()answersapproval_pending. Once approved, the usual rules hold: one spend, bound to the exact arguments, same expiry.
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.
--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. Setapproval.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.