HITL Approval Gates

HITL Approval Gates let you route high-risk AI decisions to a human approval queue using the require_approval workflow action. When a workflow step triggers this action, execution pauses until a human approves or rejects the request via the API.

This feature is available starting with the Evaluation tier (free). In Community edition, require_approval actions block the workflow but do not create a queue entry -- there is no approval API to act on them. Evaluation and Enterprise editions route them to a real approval queue with an API to approve or reject.

This page focuses on the workflow-facing approval API. If you want the broader conceptual overview, operating model, and enterprise queue context, see Human-in-the-Loop.

Evaluation Tier

HITL Approval Gates are available with a free Evaluation License — the self-serve path for self-hosted validation. Register, then set AXONFLOW_LICENSE_KEY on your server. If you already need unlimited enterprise approval operations, portal-backed workflows, or direct rollout help, apply for the Design Partner Program.

---

How It Works

1. A workflow step triggers the require_approval action (via policy enforcement or explicit step configuration)
2. The request enters the approval queue with status pending
3. A human reviewer calls the approve or reject endpoint
4. If no action is taken within 24 hours (Evaluation) or the configured TTL (Enterprise), the request is auto-rejected and the workflow is aborted
5. The workflow resumes or aborts based on the decision

This is the most practical way to add human control to multi-agent workflows. Instead of putting a human in front of every step, you only pause the steps where the decision genuinely carries business, regulatory, or security risk.

Workflow Step
    │
    ▼
require_approval triggered
    │
    ▼
┌──────────────────────┐
│  Approval Queue      │
│  status: pending     │
│  expires: 24h (eval) │
└──────────┬───────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
  Approve     Reject / Expire
     │           │
     ▼           ▼
  Resume      Abort
  workflow    workflow

Retries While Approval Is Pending

If your agent calls /gate again on the same step while the request is still waiting on a reviewer, the response keeps returning the require_approval decision. It also carries a retry_context object that makes the situation unambiguous:

• retry_context.gate_count increments on every gate call, so the agent can detect retries
• retry_context.last_decision stays "require_approval" until the approval is actioned
• retry_context.prior_completion_status stays "gated_not_completed" because no /complete has landed yet

After the approval is granted and execution eventually completes, a later gate call on that step shows prior_completion_status == "completed" — the signal a resumed agent can use to skip re-executing the business action.

If the policy or caller sets an idempotency_key on the first gate call, that key is bound to the approval for the step's lifetime. A subsequent gate or /complete with a different key (or no key after one was set) is rejected with 409 IDEMPOTENCY_KEY_MISMATCH before the approval is acted on, so an approved decision cannot be silently redirected to a different business transaction. See Retry Semantics & Idempotency for the full field reference and mismatch rules.

---

Tier Comparison

Capability	Community	Evaluation	Enterprise
require_approval action	Blocks (no queue)	Queued	Queued
Max pending requests	--	100	Unlimited
Expiry behavior	--	24h auto-reject + abort	Configurable TTL
WCP workflow-scoped approve/reject (/api/v1/workflows/.../approve|reject)	--	✅	✅
MAP plan-scoped approve/reject (/api/v1/plans/.../approve|reject)	--	✅	✅
Cross-plane response parity (same retry_context, approval_id, policies_matched)	--	✅	✅
WCP-plane pending listing (GET /api/v1/workflows/approvals/pending)	--	✅	✅
MAP-plane pending listing with plan_id (GET /api/v1/plans/approvals/pending)	--	✅	✅
?plan_id= filter on MAP pending listing	--	✅	✅
Severity metadata on approvals (derived or explicit)	✅	✅	✅
Filter queue by severity	--	✅	✅
Customer Portal UI	--	--	✅
Multi-level approval	--	--	✅
Auto-approve low-risk after delay	--	--	✅
SLA escalation for critical risk	--	--	✅

Evaluation is usually enough to prove that approval-driven workflows fit your application architecture. Enterprise becomes attractive once approvals need to be shared across teams, handled in a UI, or managed as an operational process instead of an API-only pattern.

---

API Reference

List Pending Approvals — WCP Plane

Returns all steps currently waiting for human review across WCP workflows for the caller's tenant.

curl -X GET "http://localhost:8080/api/v1/workflows/approvals/pending"

Response:

{
  "pending_approvals": [
    {
      "workflow_id": "wf-abc-123",
      "step_id": "step-2",
      "step_index": 1,
      "step_name": "risk-assessment",
      "step_type": "tool_call",
      "decision": "require_approval",
      "approval_status": "pending",
      "created_at": "2026-03-01T10:30:00Z"
    }
  ],
  "count": 1
}

Field	Type	Description
pending_approvals	array	Steps awaiting approval across all planes for the tenant
count	integer	Total matching entries (ignores limit)

This is the workflow-centric listing: it is the queue you reach for when governed workflow steps need review. For MAP-backed plans, use the plane-scoped listing below to get plan_id populated on every entry. Enterprise also exposes a broader HITL queue surface (/api/v1/hitl/queue) for richer reviewer operations that are plane-neutral.

List Pending Approvals — MAP Plane

Returns the same shape scoped to MAP-backed workflows only (workflows that were created by MAP confirm / step mode and carry a plan_id in metadata). Every entry has plan_id populated — the one intentional asymmetry with the WCP listing above, mirroring the approve/reject asymmetry in the HITL parity rule (ADR-046).

# All MAP-plane pending approvals for the tenant
curl -X GET "http://localhost:8080/api/v1/plans/approvals/pending"

# Scoped to a single plan
curl -X GET "http://localhost:8080/api/v1/plans/approvals/pending?plan_id=plan-abc123"

Response:

{
  "pending_approvals": [
    {
      "workflow_id": "wf-map-456",
      "workflow_name": "map-confirm-plan-abc123",
      "plan_id": "plan-abc123",
      "step_id": "step_0_analyze",
      "step_index": 0,
      "step_name": "Analyze customer transaction",
      "step_type": "tool_call",
      "decision": "require_approval",
      "approval_status": "pending",
      "created_at": "2026-04-22T10:00:00Z"
    }
  ],
  "count": 1
}

Available on Evaluation+ licenses (same tier gate as the MAP step approve/reject endpoints). Reviewer integrators that need to render plan context can read plan_id directly from the response without a second lookup; clients that want a plane-neutral view can use /api/v1/hitl/queue (Enterprise) instead.

Approve a Request

Approves a pending request and resumes the workflow. The approver identity is extracted from the X-User-ID header. An audit comment (minimum 10 characters) is required so every approval carries a justification into the audit log.

curl -X POST "http://localhost:8080/api/v1/workflows/wf-abc-123/steps/step-2/approve" \
  -H "Content-Type: application/json" \
  -H "X-User-ID: compliance-officer-7" \
  -d '{"comment": "Approved after full audit review of the payment intent"}'

Response:

{
  "workflow_id": "wf-abc-123",
  "step_id": "step-2",
  "decision": "allow",
  "reason": "Approved: High-value transfer requires oversight",
  "approval_status": "approved",
  "approval_id": "318a270f-7b42-5c56-a191-8dbd1bf2e1e4",
  "approved_by": "compliance-officer-7",
  "approved_at": "2026-04-22T10:05:00Z",
  "policies_matched": [
    {
      "policy_id": "f9b22075-7e59-4ba2-a31e-bb6e059ae96b",
      "policy_name": "High-Value Wire Transfer Oversight",
      "action": "require_approval",
      "risk_level": "high",
      "allow_override": false,
      "policy_description": "Require human approval on transactions above $10,000"
    }
  ],
  "retry_context": {
    "gate_count": 1,
    "completion_count": 0,
    "prior_completion_status": "none",
    "prior_output_available": false,
    "prior_output": null,
    "prior_completion_at": null,
    "idempotency_key": "payment-intent-123",
    "last_decision": "require_approval",
    "first_attempt_at": "2026-04-22T10:00:00Z",
    "last_attempt_at": "2026-04-22T10:00:00Z"
  },
  "message": "Step approved"
}

decision resolves to allow so the agent that re-calls /gate next will see the step cleared. retry_context mirrors the Retry Semantics & Idempotency shape, so reviewer tools render retry state without a second API call.

Reject a Request

Rejects a pending request and aborts the workflow. An audit reason (minimum 10 characters) is required.

curl -X POST "http://localhost:8080/api/v1/workflows/wf-abc-123/steps/step-2/reject" \
  -H "Content-Type: application/json" \
  -H "X-User-ID: compliance-officer-7" \
  -d '{"reason": "Output contains PII that was not redacted"}'

Response:

{
  "workflow_id": "wf-abc-123",
  "step_id": "step-2",
  "decision": "block",
  "reason": "Rejected: Output contains PII that was not redacted",
  "approval_status": "rejected",
  "approval_id": "318a270f-7b42-5c56-a191-8dbd1bf2e1e4",
  "rejected_by": "compliance-officer-7",
  "rejected_at": "2026-04-22T10:05:00Z",
  "policies_matched": [
    {
      "policy_id": "8b3c9e21-4f7a-4d5e-bb88-112233445566",
      "policy_name": "PII Redaction Required",
      "action": "require_approval",
      "risk_level": "high",
      "allow_override": false,
      "policy_description": "Outputs containing unredacted PII require human review"
    }
  ],
  "retry_context": {
    "gate_count": 1,
    "completion_count": 0,
    "prior_completion_status": "none",
    "prior_output_available": false,
    "prior_output": null,
    "prior_completion_at": null,
    "idempotency_key": "",
    "last_decision": "require_approval",
    "first_attempt_at": "2026-04-22T10:00:00Z",
    "last_attempt_at": "2026-04-22T10:00:00Z"
  },
  "message": "Step rejected, workflow aborted"
}

decision resolves to block and the workflow is aborted. approved_by / approved_at stay absent; rejected_by / rejected_at carry the reviewer identity.

MAP Plan-Scoped Equivalents

The multi-agent planning (MAP) API exposes the same approval shape at the plan level — available at Evaluation or Enterprise tier, consistent with the workflow-scoped endpoints:

# Approve a plan step
curl -X POST "http://localhost:8080/api/v1/plans/plan-abc123/steps/step_0_analyze/approve" \
  -H "Content-Type: application/json" \
  -H "X-User-ID: compliance-officer-7" \
  -d '{"comment": "Approved after full audit review"}'

# Reject a plan step
curl -X POST "http://localhost:8080/api/v1/plans/plan-abc123/steps/step_0_analyze/reject" \
  -H "Content-Type: application/json" \
  -H "X-User-ID: compliance-officer-7" \
  -d '{"reason": "Transaction flagged by compliance policy"}'

# List MAP-plane pending approvals (optionally filtered to one plan)
curl -X GET "http://localhost:8080/api/v1/plans/approvals/pending?plan_id=plan-abc123"

The MAP approve/reject response is identical to the WCP response shown above, plus a plan_id field echoing the plan path parameter. The MAP pending-list response has the same {pending_approvals, count} shape as the WCP pending-list response, with plan_id populated on every entry. Both planes project through the same helper — so a field added to any HITL response surfaces on both endpoints automatically. See ADR-046 for the parity rule.

Tier note

Before v7.4.0 the MAP plan-scoped approve/reject endpoints were Enterprise-only. In v7.4.0 they were lowered to Evaluation+ to match the WCP workflow-scoped endpoints — a reviewer tool that integrates with either plane now sees the same tier gate. MAP confirm / step execution modes (the entry-side that creates the approval-gated plan) remain Enterprise-only.

---

Evaluation Tier Limits

Limit	Value
Max pending approvals	100
Auto-expiry	24 hours (auto-reject + workflow abort)
Interface	API only (no Portal UI)
Escalation	Not available (Enterprise only)
Multi-level approval	Not available (Enterprise only)

When the 100 pending limit is reached, new require_approval actions will return an error until existing requests are approved, rejected, or expired.

Auto-Expiry

In the Evaluation tier, pending requests that are not acted on within 24 hours are automatically rejected. The associated workflow is aborted and the expiry is recorded in the audit log.

---

Creating Policies with require_approval

Define policies that trigger human review when specific conditions are met:

curl -X POST http://localhost:8080/api/v1/static-policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "name": "high-value-transaction-oversight",
    "description": "Require human approval on transactions flagged as high value",
    "pattern": "(amount|value|total).*\\$[1-9][0-9]{4,}",
    "action": "require_approval",
    "severity": "high",
    "category": "security-sqli",
    "priority": 900,
    "enabled": true
  }'

The endpoint is /api/v1/static-policies (hyphenated, plural). Static policies are regex-pattern policies; the shape uses a singular action string and a pattern field. See System Policy API for the full reference. For retry-aware or step-context policies, use the dynamic policy endpoint /api/v1/policies instead — see WCP Policy Configuration.

When a workflow step matches this policy, the request enters the approval queue instead of proceeding automatically.

In practice, teams usually combine this with:

• workflow step names that make reviewer intent obvious
• reviewer identity in X-User-ID
• application-side handling for rejection or expiry
• policy simulation before rollout so approval gates are not overly broad

Risk-Tiered Severity

Each approval request carries a severity level (critical, high, medium, low) that reflects the risk of the action being approved. Severity is determined in two ways:

1. Explicit: set severity in the policy's require_approval action config:

{
  "type": "require_approval",
  "config": {
    "reason": "High-value transaction requires review",
    "severity": "critical"
  }
}

2. Derived: if no explicit severity is configured, it is derived from the policy check's risk score:
   • Risk score >= 0.8: critical
   • Risk score >= 0.5: high
   • Risk score >= 0.3: medium
   • Risk score < 0.3: low

Severity is visible in the queue listing and can be used to filter approvals:

# List only critical approvals
curl http://localhost:8080/api/v1/hitl/queue?severity=critical

In Enterprise edition, severity also drives operational automation: low-risk requests can be auto-approved after a configurable delay, and critical requests trigger escalation when they exceed an SLA threshold.

require_approval as an override action

Starting on platform v7.2.0, require_approval is also a valid action_override value when creating a session-scoped override via POST /api/v1/overrides. Before v7.2.0 the override validator silently dropped it (the allow-list was hand-written as {block, redact, warn, log}), so operators who wanted to temporarily route a specific policy's decisions into the HITL queue had to edit the policy itself. The canonical terminal-action list is now block, require_approval, redact, warn, log. See Overrides API for the full request shape.

---

Audit Trail

All approval gate activity is recorded in the audit log:

• Request entering the queue (with policy name, step name, metadata)
• Approval or rejection (with reviewer ID, timestamp)
• Auto-expiry events (with original request details and workflow abort)

Audit retention follows your tier limits: 14 days for Evaluation, configurable up to 10 years for Enterprise.

---

Enterprise: Visual Approval Dashboard

On Enterprise tier, approvals can be managed through the Customer Portal Approval Dashboard instead of API calls.

The dashboard provides:

• A live queue of all pending approvals with workflow context and policy triggers
• One-click expand to see matched policies, decision reasons, and step input JSON
• Approve/reject with mandatory justification (min 10 characters) for audit compliance
• Real-time badge count in the navigation bar (polls every 30 seconds)
• Auto-dismissing success messages and optimistic removal for responsive UX

This is the same approval API documented above, wrapped in a production-grade web interface designed for compliance officers and operations teams who need to review AI decisions without writing code.

That distinction is important commercially and operationally:

• Evaluation proves the workflow design and approval semantics.
• Enterprise is what teams usually want once reviewers are not all engineers and the approval process itself needs to scale.

Learn more: Customer Portal

---

Related Documentation

• Human-in-the-Loop Overview -- Full HITL documentation including Enterprise features
• Retry Semantics & Idempotency -- retry_context and idempotency_key behavior on step gates, including the approval-pending retry case
• Customer Portal -- Enterprise web portal with Approval Dashboard and Execution Timeline
• Policy Simulation & Impact Report -- Test policies before deploying
• Evidence Export Pack -- Export approval records for review
• Community vs Enterprise -- Full feature comparison