Operator - Approvals

Overview

Approval requests pause gateway actions that policy sends to human review. The record combines the requested action, submitted payload, policy, expiry, decision, and any queued execution outcome so a reviewer can decide with context.

Decision and execution differ

Approved means the review gate passed; execution is queued separately. Read execution.status, execution.trace_id, and execution.error to determine whether the action actually ran. A rejection never requests execution.

Reviewer roles are policy data

Owner or admin status is not an automatic override when a policy names different reviewers. The decision path checks the membership role or an enabled custom workspace role against policy.reviewer_roles.

Submitted payloads remain visible

The authorizer stores attrs.payload on the approval request and returns it to operator readers without a sanitizer in this path. Callers must remove credentials, tokens, personal data, and other secrets before requesting the action.

How it works

1. Triage the queue

   List requests with filter[status]=pending, open the detail, and confirm it has not expired or already been decided. Treat payload as sensitive submitted content, and correlate trace_id with observability when context is unclear.

2. Decide, then verify

   Approve or reject once with concise notes. After an approval, re-read the request until execution reaches a terminal state; use the returned execution trace or error for follow-up.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

const response = await fetch("/api/v1/operator/approval_requests?filter%5Bstatus%5D=pending", {
  credentials: "same-origin",
  headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);

Troubleshooting

Decision returns 403

Confirm the membership is not auditor and that the policy's reviewer_roles contains the built-in membership role or one of the user's enabled custom roles.

A request cannot be decided

It may already be approved, rejected, or expired. Re-read the detail instead of retrying blindly; decisions are serialized to prevent two reviewers from racing.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "approval_requests": [
    {
      "id": "a2b3c4d5-e6f7-4890-abcd-ef1234567890",
      "inserted_at": "2026-03-25T10:00:00Z",
      "payload": {
        "action": "deploy",
        "target": "production"
      },
      "request_type": "gateway_execute",
      "service_agent_id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
      "status": "pending",
      "updated_at": "2026-03-25T10:00:00Z",
      "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
    }
  ],
  "next_cursor": null
}

{
  "id": "a2b3c4d5-e6f7-4890-abcd-ef1234567890",
  "inserted_at": "2026-03-25T10:00:00Z",
  "payload": {
    "action": "deploy",
    "target": "production"
  },
  "request_type": "gateway_execute",
  "service_agent_id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
  "status": "pending",
  "updated_at": "2026-03-25T10:00:00Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}

{
  "id": "a2b3c4d5-e6f7-4890-abcd-ef1234567890",
  "inserted_at": "2026-03-25T10:00:00Z",
  "payload": {
    "action": "deploy",
    "target": "production"
  },
  "request_type": "gateway_execute",
  "service_agent_id": "f4d49601-3477-4c9d-b896-ac08a26a3147",
  "status": "approved",
  "updated_at": "2026-03-25T10:00:00Z",
  "workspace_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea"
}