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. Register at getaxonflow.com/evaluation-license and set AXONFLOW_LICENSE_KEY on your server.

---

How It Works

1. A workflow step triggers the require_approval action (via policy evaluation 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

---

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
Approve/reject API	--	✅	✅
List pending API	--	✅	✅
Customer Portal UI	--	--	✅
Multi-level approval	--	--	✅
SLA escalation	--	--	✅

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

Returns all steps currently waiting for human review.

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

Response:

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

Field	Type	Description
pending_approvals	array	List of steps awaiting approval
count	integer	Number of pending approvals returned

This endpoint is workflow-centric: it is the queue you use when governed workflow steps need review. Enterprise also exposes a broader HITL queue surface for richer reviewer operations, but the workflow approval endpoints are the right starting point for most engineering teams.

Approve a Request

Approves a pending request and resumes the workflow. The approver identity is extracted from the X-User-ID header.

curl -X POST "http://localhost:8080/api/v1/workflows/wf-abc-123/steps/step-2/approve" \
  -H "X-User-ID: compliance-officer-7"

Response:

{
  "workflow_id": "wf-abc-123",
  "step_id": "step-2",
  "approval_status": "approved",
  "approved_by": "compliance-officer-7",
  "message": "Step approved"
}

Reject a Request

Rejects a pending request and aborts the workflow. The rejector identity is extracted from the X-User-ID header.

curl -X POST "http://localhost:8080/api/v1/workflows/wf-abc-123/steps/step-2/reject" \
  -H "X-User-ID: compliance-officer-7"

Response:

{
  "workflow_id": "wf-abc-123",
  "step_id": "step-2",
  "approval_status": "rejected",
  "rejected_by": "compliance-officer-7",
  "message": "Step rejected, workflow aborted"
}

---

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/policies/static \
  -H "Content-Type: application/json" \
  -H "X-Org-ID: my-org" \
  -d '{
    "name": "high-value-transaction-oversight",
    "pattern": "(amount|value|total).*\\$[1-9][0-9]{4,}",
    "action": "require_approval",
    "severity": "high",
    "enabled": true
  }'

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

---

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
• 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