Async Approvals¶
Editions: OSS, Cloud, Enterprise. Unless stated otherwise, everything on this page ships in OSS.
Reference-only approvals have different replay and original-argument rules. See Sensitive-data handling before enabling asynchronous replay for sensitive tool calls.
After reading this page you can switch an approval workflow to non-blocking mode, so agents get a request_id back immediately and poll for the decision instead of holding an MCP connection open.
Overview¶
By default, when a tool call requires approval, the MCP connection blocks: the agent waits until a human approves or declines. This works well for interactive sessions but has two drawbacks:
- Client timeouts. Most MCP clients default to 30–60 s; approval can take minutes.
- Blocked agents. The agent cannot do other work while waiting.
Async approval mode solves both problems. Instead of blocking, the tool call returns immediately with a pending_approval status and a request_id. The agent then polls get_approval_status(request_id) until the human decides, at which point the tool executes and the result is returned in the poll response.
Agent ──▶ call tool ──▶ Preloop returns {status: "pending_approval", request_id: "..."}
Agent ──▶ get_approval_status(request_id) ──▶ {status: "pending", remaining_seconds: 280}
Agent ──▶ get_approval_status(request_id) ──▶ {status: "approved", tool_result: {...}}
Configuration¶
Via Policy YAML¶
Enable async approval on an approval workflow:
version: "1.0"
metadata:
name: async-deploy-review
approval_workflows:
- name: "deploy-review"
timeout_seconds: 600
approvals_required: 1
async_approval: true # ← enables async mode
tools:
- name: "bash"
source: mcp
approval_workflow: "deploy-review"
conditions:
- expression: "args.command.contains('deploy')"
action: require_approval
Via Web UI¶
- On Tools, open Workflows and edit a workflow or choose New workflow
- Turn on Enable Async Approvals
- Click Create Policy or Save Changes
Polling Flow¶
1. Tool Call Returns Immediately¶
When async approval is enabled, the tool call does not block. The agent receives:
{
"status": "pending_approval",
"request_id": "8f14e45f-…",
"message": "Approval request sent via email, mobile_push. Poll the approval status by calling get_approval_status(request_id='8f14e45f-…')",
"poll_interval_seconds": 15,
"timeout_seconds": 600,
"channels": ["email", "mobile_push"]
}
Note the agent-facing status string is pending_approval; on subsequent polls the stored request status is pending.
2. Agent Polls for Decision¶
The agent calls get_approval_status(request_id) periodically. The response carries the request status plus an event log of everything that has happened so far (notifications sent, votes cast, escalations):
{
"request_id": "8f14e45f-…",
"status": "pending",
"tool_name": "bash",
"events": [
{"timestamp": "2026-07-17T20:00:01Z", "type": "notification_sent", "detail": "…"}
],
"remaining_seconds": 280
}
remaining_seconds is present only while the request is pending. Once any approver has voted, approvals_received is included.
3. Human Decides¶
The human approves or declines via mobile app, email, Slack, or web UI.
4. Agent Receives Result¶
On the next poll after approval, the tool executes and the response includes its result:
{
"request_id": "8f14e45f-…",
"status": "approved",
"tool_name": "bash",
"events": [
{"timestamp": "2026-07-17T20:02:15Z", "type": "vote", "detail": "…", "comment": "Looks good, ship it."}
],
"approvals_received": 1,
"tool_result": {
"text": "Deployment completed successfully."
}
}
Approver comments appear as comment entries in the event log. If declined, status is "declined" and no tool_result is present. If a concurrent poll is already executing the tool, the response reports status: "executing": poll again for the cached result. If execution failed, the poll returns tool_execution_error instead of re-running the tool.
State Transitions¶
┌─────────┐
│ pending │──── human approves ───▶ approved ──▶ tool executes ──▶ result cached
│ │──── human declines ───▶ declined
│ │──── request cancelled ─▶ cancelled
│ │──── timeout reached ──▶ expired
└─────────┘
| State | Description |
|---|---|
pending |
Waiting for human decision (reported as pending_approval in the initial tool response) |
approved |
Human approved; tool result available |
executing |
Computed status while another poll is running the approved tool: poll again |
declined |
Human declined; tool not executed |
cancelled |
Request was cancelled; tool not executed |
expired |
Timeout reached without a decision |
Idempotency: Once a tool result is cached on an approved request, subsequent polls return the same cached result without re-executing the tool.
Client Configuration¶
Because the tool call returns immediately in async mode, no client timeout increase is needed. The agent polls at its own pace.
If you are using synchronous (blocking) approval mode instead, you may need to increase your MCP client timeout. See the timeout guidance in your MCP client reference page, such as Claude Code.
API Reference¶
get_approval_status (MCP tool)¶
Called by the agent to poll approval status.
| Parameter | Type | Required | Description |
|---|---|---|---|
request_id |
string | Yes | The approval request ID returned by the original tool call |
REST Endpoints¶
| Endpoint | Description |
|---|---|
GET /api/v1/approval-requests/{id} |
Get approval request details (authenticated) |
POST /api/v1/approval-requests/{id}/approve |
Approve a request (body optional: {"comment": "..."}) |
POST /api/v1/approval-requests/{id}/decline |
Decline a request (body optional: {"comment": "..."}) |
POST /api/v1/approval-requests/{id}/decide |
Approve or decline ({"approved": true\|false} required) |
GET /approval/{id}/data?token={token} |
Public token-based access |
POST /approval/{id}/approve?token={token} |
Public token-based approve (the webhook decision.approve_url) |
POST /approval/{id}/decline?token={token} |
Public token-based decline (the webhook decision.decline_url) |
POST /approval/{id}/decide?token={token} |
Public token-based decision ({"action": "approve"\|"decline"}) |
Best Practices¶
- Set reasonable timeouts. 10 minutes (
timeout_seconds: 600) works for most workflows. - Use with agentic flows. Async approval is ideal for automated flow executions where the agent runs unattended.
- Combine with justification. Require agents to explain why they need the tool: reviewers see the justification in the approval notification. See Per-Tool Justification.
- Monitor via WebSocket. Subscribe to the
approvalstopic for real-time approval status updates in the UI.
Native tool calls too
Approvals are not limited to MCP tools. Onboarded agents can route their native tool calls (shell commands, file edits) through Preloop approvals, see Native Tool Approvals.
Investigate a refused native tool call¶
The agent permission-check endpoint records refusals as
agent_permission_denied, including known credentials rejected with 401/403
before policy evaluation. Audit details contain the principal, tool target,
reason_code, a plain message, and an attempt count. For example:
GET /api/v1/audit-logs?action=agent_permission_denied&reason_code=api_key_scope_denied
GET /api/v1/audit-logs/grouped?reason_code=tool_blocked
Use a human credential with view_audit_logs. Useful reasons include
key_inactive, key_expired, api_key_scope_denied, runtime_binding_invalid,
session_ended, execution_ended, agent_inactive, client_policy_denied,
tool_blocked, approval_unavailable, approval_denied, approval_expired,
and approval_pending. permission_denied identifies a refusal from an access
rule and retains its bounded, redacted explanation. Different explanations have
separate counters. Approver comments are excluded; approval lifecycle records
remain available separately.
Identical refusals share one row per principal, tool, reason, and UTC minute.
details.count counts all attempts, while the API's total counts rows. The row
is visible immediately, and its final count joins the hash chain after the minute
closes. Retries in later minutes cannot edit sealed evidence. Tool names are
bounded and redacted; tool arguments and credentials are never copied into the
refusal record. Unknown credentials have no trusted account attribution.
Ending an already-ended runtime session returns its existing summary without another lifecycle audit row or session-ended event. A turn's Stop event does not end the conversation. Native terminal hooks suppress successful repeat delivery; failed delivery can be retried safely.