Human-in-the-Loop Approvals

For sensitive operations, require a human to approve before the agent proceeds.

Two Levels

Level	Who Approves	Use Case
self	The agent's owner	Creating issues, sending messages
admin	An administrator	Merging PRs, deleting resources, financial operations

Configuring HITL

Set hitl on a tool when registering a server:

-d '{
    "allowedTools": [
      { "name": "list_issues", "tier": "low" },
      { "name": "create_issue", "tier": "medium", "hitl": "self" },
      { "name": "merge_pr", "tier": "high", "hitl": "admin" }
    ]
  }'

Lifecycle

Deny with Reason

When denying an approval, provide a reason:

curl -X POST https://api.wardenauthz.com/v1/scope/{scopeId}/mcp/approvals/{approvalId}/approve \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "approved": false,
    "reason": "This PR needs more review before merging"
  }'

The reason is shown to the agent and recorded in the approval history.

Auto-Reject Timeout

Approvals have a 1-hour decision window. If no decision is made, the request auto-rejects (timed-out) and a fresh pending request is opened on the next tool call.

History & Accountability

Every approval decision is recorded with:

• Who approved/denied it
• When
• The reason (if denied)
• The tool, server, and context

View approval history via the dashboard or API:

curl -X GET https://api.wardenauthz.com/v1/mcp/approvals/history \
  -H "x-api-key: ak_live_..."

Wait Messages

When a tool call is pending approval, the agent receives a wait message with a deep link:

• Self-approval: "This action needs your explicit approval — approve it at https://app.wardenauthz.com/connections?approval={id}"
• Admin-approval: "This action needs approval from an administrator"

The deep link works on mobile via the PWA, so you can approve from anywhere.

Full API Reference

Complete request/response schemas, examples, and try-it-out are available in the API Reference.