Skip to main content

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.

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
Workflow Step
    │
    ▼
require_approval triggered
    │
    ▼
┌──────────────────────┐
│  Approval Queue      │
│  status: pending     │
│  expires: 24h (eval) │
└──────────┬───────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
  Approve     Reject / Expire
     │           │
     ▼           ▼
  Resume      Abort
  workflow    workflow

Tier Comparison​

CapabilityCommunityEvaluationEnterprise
require_approval actionBlocks (no queue)QueuedQueued
Max pending requests--100Unlimited
Expiry behavior--24h auto-reject + abortConfigurable TTL
Approve/reject API--✅✅
List pending API--✅✅
Customer Portal UI----✅
Multi-level approval----✅
SLA escalation----✅

API Reference​

List Pending Approvals​

Returns all steps currently waiting for human review.

curl -X GET "http://localhost:8081/api/v1/workflows/approvals/pending" \
  -H "X-Tenant-ID: my-org"

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
}
FieldTypeDescription
pending_approvalsarrayList of steps awaiting approval
countintegerNumber of pending approvals returned

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:8081/api/v1/workflows/wf-abc-123/steps/step-2/approve" \
  -H "X-Tenant-ID: my-org" \
  -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:8081/api/v1/workflows/wf-abc-123/steps/step-2/reject" \
  -H "X-Tenant-ID: my-org" \
  -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​

LimitValue
Max pending approvals100
Auto-expiry24 hours (auto-reject + workflow abort)
InterfaceAPI only (no Portal UI)
EscalationNot available (Enterprise only)
Multi-level approvalNot 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.

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.

Last updated on