Approvals API¶

The Approvals API manages the human-in-the-loop approval queue (INV-002). When the policy engine assigns a verdict of ESCALATE to a connector operation, an approval request is created and sent to configured notification channels (Slack, Teams, webhooks). The Approvals API allows authorized users to list, inspect, and review pending approval requests.

All endpoints are scoped to the authenticated user's organization via Row-Level Security.

List Approvals¶

Retrieves all approval requests for the organization, with optional filtering by status and agent.

• Method: GET
• Path: /v1/approvals
• Required Role: Any authenticated user

Query Parameters¶

Response¶

{
  "approvals": [
    {
      "id": "apr-uuid",
      "org_id": "org-uuid",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "policy_id": "policy-uuid",
      "action_type": "connector.called",
      "connector": "crowdstrike",
      "action_detail": {
        "operation": "hosts:contain",
        "params": { "host_id": "host-123" }
      },
      "risk_score": 85,
      "status": "pending",
      "requested_at": "2026-04-10T16:30:00Z",
      "reviewed_by": null,
      "reviewed_at": null,
      "review_notes": null,
      "expires_at": "2026-04-10T17:30:00Z"
    }
  ],
  "total": 1
}

Example¶

curl -X GET "https://api.arxsec.io/v1/approvals?status=pending" \
  -H "Authorization: Bearer {token}"

List Pending Approvals¶

Retrieves only pending approval requests that have not expired. This is a convenience endpoint optimized for approval queue dashboards.

• Method: GET
• Path: /v1/approvals/pending
• Required Role: Any authenticated user

Example¶

curl -X GET "https://api.arxsec.io/v1/approvals/pending" \
  -H "Authorization: Bearer {token}"

Response¶

Returns the same schema as the List Approvals endpoint, filtered to status: "pending" with expires_at in the future.

Check Approval Status¶

Checks the current status of an approval request. Agents poll this endpoint to determine when a human has made a decision on an escalated action.

• Method: GET
• Path: /v1/approvals/{approval_id}/status
• Required Role: Any authenticated user

Path Parameters¶

Example¶

curl -X GET "https://api.arxsec.io/v1/approvals/apr-uuid/status" \
  -H "Authorization: Bearer {token}"

Response¶

{
  "approval_id": "apr-uuid",
  "status": "approved"
}

Possible status values: pending, approved, denied, expired.

Review Approval¶

Approves or denies a pending approval request.

• Method: POST
• Path: /v1/approvals/{approval_id}/review
• Required Role: admin or deployer

Path Parameters¶

Request Body¶

Example¶

curl -X POST "https://api.arxsec.io/v1/approvals/apr-uuid/review" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "review_notes": "Verified host compromise indicators. Containment authorized."
  }'

Response¶

{
  "id": "apr-uuid",
  "org_id": "org-uuid",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "policy_id": "policy-uuid",
  "action_type": "connector.called",
  "connector": "crowdstrike",
  "action_detail": {
    "operation": "hosts:contain",
    "params": { "host_id": "host-123" }
  },
  "risk_score": 85,
  "status": "approved",
  "requested_at": "2026-04-10T16:30:00Z",
  "reviewed_by": "user-uuid",
  "reviewed_at": "2026-04-10T16:35:00Z",
  "review_notes": "Verified host compromise indicators. Containment authorized.",
  "expires_at": "2026-04-10T17:30:00Z"
}

Returns 404 if the approval request is not found. Returns 409 Conflict if the approval has already been reviewed. Returns 410 Gone if the approval has expired. The review decision is audit-logged with the decision, risk score, and reviewer notes. Notifications are sent to configured channels (Slack, Teams, webhooks) upon review.