Human-in-the-Loop Approvals

Human-in-the-Loop Approvals enable agentic AI systems to pause execution and request explicit authorization from human reviewers before performing sensitive or high-impact operations—such as publishing content, transferring funds, or executing database mutations.

 Agent Runtime (Python SDK / cURL)
            │
            ▼
 1. POST /api/v1/approvals   ──►  Infralo Platform
 (Workspace API Key)                        │
                                            ▼
                                2. Dashboard Review Queue
                                (Approve / Reject decision)
                                            │
                                            ▼
 4. Resume Local Workflow   ◄── 3. Webhook Callback
                                (Encrypted Payload)

How It Works

1. Request Initiation: An AI agent initiates an approval request using the Python SDK or a direct HTTP request authenticated with a Workspace API Key (vk_...).
2. Review Queue: The approval request enters a pending state and appears in your workspace's Approvals dashboard queue.
3. Human Decision: Team members review the contextual payload, prompt details, and attached structured data in the dashboard, then click Approve or Reject.
4. Webhook Callback: Upon decision, Infralo's background worker sends an HTTP POST request to your specified callback_url to notify your application and resume the workflow.

Creating Approval Requests

You can request approvals programmatically using the Python SDK or via direct HTTP calls.

Option 1: Using the Python SDK (Recommended)

The easiest way to integrate approvals into Python agents is using the official infralo package. When called inside an active trace context, trace_id is automatically attached.

from infralo import Infralo

infralo = Infralo(api_key="vk_your_workspace_api_key")

# Asynchronous agent usage
approval = await infralo.acreate_approval(
    title="Publish Stock Recap to Threads",
    description="Please review and approve publishing today's stock recap.",
    review_data={
        "recap_text": "IDX Market Recap for July 21...",
        "target_platform": "Threads"
    },
    callback_url="https://agent-service.example.com/api/callback",
    callback_headers={"x-api-key": "secret_agent_token"},
    client_reference_id="run_8812"
)

print("Approval Created:", approval["approval_id"])

📘 Full SDK Reference: For detailed method signatures, async/sync examples, and parameter references, check out the dedicated Python SDK Approvals Guide.

Option 2: Using cURL / HTTP API

If you are building an agent in TypeScript, Go, or another language, send a POST request to /api/v1/approvals using your Workspace API Key (vk_...).

curl -X POST "https://api.infralo.com/api/v1/approvals" \
  -H "Authorization: Bearer vk_your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Publish Stock Recap to Threads",
    "description": "Please review and approve publishing today'\''s stock recap.",
    "review_data": {
      "recap_text": "IDX Market Recap for July 21...",
      "target_platform": "Threads"
    },
    "callback_url": "https://agent-service.example.com/api/callback",
    "callback_headers": {
      "x-api-key": "secret_agent_token"
    },
    "client_reference_id": "run_8812",
    "trace_id": "7f8b9a0c-1234-4567-89ab-cdef01234567"
  }'

Expected API Response (200 OK)

{
  "message": "Approval request created successfully",
  "data": {
    "approval_id": "3a1c2d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "workspace_id": "11111111-2222-3333-4444-555555555555",
    "title": "Publish Stock Recap to Threads",
    "description": "Please review and approve publishing today's stock recap.",
    "review_data": {
      "recap_text": "IDX Market Recap for July 21...",
      "target_platform": "Threads"
    },
    "callback_url": "https://agent-service.example.com/api/callback",
    "client_reference_id": "run_8812",
    "status": "pending",
    "callback_status": "pending",
    "created_at": "2026-07-21T18:00:00Z"
  }
}

Security & SSRF Protection

Because approval callbacks trigger HTTP requests to external webhook URLs, Infralo enforces multi-layer Server-Side Request Forgery (SSRF) security guards:

• Non-blocking DNS Resolution: Hostnames are resolved in an isolated thread pool with a 10-second timeout.
• Strict IP Blocklist Validation: Resolved IPs are validated against private, loopback, link-local, carrier-grade NAT, and cloud metadata addresses (including AWS 169.254.169.254).
• Direct-IP Execution: The validated IP is stored and pinned for the webhook execution, preventing DNS rebinding attacks.
• Encrypted Headers: Custom callback headers (like API keys) are stored encrypted at rest.

Dashboard Review Console

In the Infralo dashboard (Workspaces > Approvals):

• Filter Requests: Manage Pending, Approved, and Rejected requests.
• Inspect Context: View attached structured review_data, agent description, and client reference IDs.
• Trace Linkage: Jump directly from an approval request into the full execution trace to audit prompt history and tool calls prior to approving.
• Manual Callback Retry: If your webhook service was temporarily offline, click Retry Callback to re-deliver the decision notification.