Approvals API¶

Manage just-in-time (JIT) access requests for restricted tools. When an agent attempts to call a tool with requireApproval: true and no existing access policy, the platform creates an access request that must be approved by an admin before the agent can proceed.

Create Access Request¶

POST /governance/requests

Create a new access request. This endpoint is idempotent -- if a pending request already exists for the same subject and tool, the existing request is returned.

Request Body¶

curl -X POST https://api.runagents.io/governance/requests \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "payment-agent-sa",
    "tool_id": "stripe-api",
    "agent_id": "payment-agent",
    "duration": "4h",
    "run_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "capability": "create-charge",
    "payload_hash": "sha256:abc123"
  }'

import requests

resp = requests.post(
    "https://api.runagents.io/governance/requests",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "subject": "payment-agent-sa",
        "tool_id": "stripe-api",
        "agent_id": "payment-agent",
        "duration": "4h",
        "run_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    },
)
print(resp.json())

Response (201 Created)¶

{
  "id": "req-a1b2c3d4-e5f6-7890",
  "status": "PENDING",
  "action_id": "act-x1y2z3"
}

Idempotency¶

If a PENDING request already exists for the same subject and tool_id, the existing request is returned with a 200 OK instead of creating a duplicate.

List Access Requests¶

GET /governance/requests

List access requests. By default, returns requests in PENDING status.

Query Parameters¶

# List pending requests
curl https://api.runagents.io/governance/requests \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

# List approved requests
curl "https://api.runagents.io/governance/requests?status=APPROVED" \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

Response (200 OK)¶

[
  {
    "id": "req-a1b2c3d4-e5f6-7890",
    "subject": "payment-agent-sa",
    "agent_id": "payment-agent",
    "tool_id": "stripe-api",
    "status": "PENDING",
    "duration": "4h",
    "created_at": "2026-02-23T10:00:00Z",
    "updated_at": "2026-02-23T10:00:00Z"
  }
]

Get Access Request Details¶

GET /governance/requests/:id

Retrieve details for a specific access request.

Path Parameters¶

curl https://api.runagents.io/governance/requests/req-a1b2c3d4-e5f6-7890 \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

Response (200 OK)¶

{
  "id": "req-a1b2c3d4-e5f6-7890",
  "subject": "payment-agent-sa",
  "agent_id": "payment-agent",
  "tool_id": "stripe-api",
  "status": "PENDING",
  "duration": "4h",
  "created_at": "2026-02-23T10:00:00Z",
  "updated_at": "2026-02-23T10:00:00Z"
}

Approve Access Request¶

POST /governance/requests/:id/approve

Approve a pending access request. This creates a time-limited access policy that allows the agent to call the tool.

Path Parameters¶

curl -X POST https://api.runagents.io/governance/requests/req-a1b2c3d4-e5f6-7890/approve \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests

resp = requests.post(
    "https://api.runagents.io/governance/requests/req-a1b2c3d4-e5f6-7890/approve",
    headers={"Authorization": f"Bearer {api_key}"},
    json={},
)
print(resp.json())

Response (200 OK)¶

{
  "id": "req-a1b2c3d4-e5f6-7890",
  "subject": "payment-agent-sa",
  "agent_id": "payment-agent",
  "tool_id": "stripe-api",
  "status": "APPROVED",
  "duration": "4h",
  "approver_id": "admin@example.com",
  "expires_at": "2026-02-23T14:00:00Z",
  "created_at": "2026-02-23T10:00:00Z",
  "updated_at": "2026-02-23T10:05:00Z"
}

What happens on approval¶

1. A time-limited access policy is created granting the agent access to the tool
2. The policy expires after the requested duration (default: 4 hours)
3. If the request was associated with a run, the corresponding blocked action is marked as APPROVED
4. The platform's resume worker automatically detects approved actions and resumes paused runs

Errors¶

Reject Access Request¶

POST /governance/requests/:id/reject

Reject a pending access request.

Path Parameters¶

curl -X POST https://api.runagents.io/governance/requests/req-a1b2c3d4-e5f6-7890/reject \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not authorized for production Stripe access"}'

Request Body (optional)¶

Response (200 OK)¶

{
  "id": "req-a1b2c3d4-e5f6-7890",
  "subject": "payment-agent-sa",
  "tool_id": "stripe-api",
  "status": "REJECTED",
  "reason": "Not authorized for production Stripe access",
  "updated_at": "2026-02-23T10:05:00Z"
}

Access Request Lifecycle¶

PENDING --> APPROVED --> (auto) EXPIRED
PENDING --> REJECTED

Automatic Expiry¶

When an access request is approved, the platform creates an access policy with a TTL (default: 4 hours, configurable per tool via governance.approval.defaultDuration). When the TTL expires:

1. The access policy is automatically removed by the garbage collector
2. The access request status transitions to EXPIRED
3. The agent can no longer call the tool until a new request is approved

{
  "governance": {
    "approval": {
      "defaultDuration": "8h",
      "autoExpire": true
    }
  }
}

Access Request Object Reference¶