Skip to content

Approve or deny held agent calls and access requests by API

Approvals happen in the AtmanID console by default. If your approvers live somewhere else, such as a Slack bot, a ServiceNow form or an on-call runbook, that tool can make the decision through the API. The decision belongs to the person who owns the API key. AtmanID checks that person exactly as it would in the console and records the decision the same way, with the API key’s id attached.

Before you start

A key decides as the person who created it, so create one key per approver and keep it with them; a shared key would hide who decided. Creating API keys needs the Manage API keys permission (identity administrators and tenant owners), and keys with these scopes are high impact: they wait for approval before they are issued. Pick the scope you need:

Scope Lets the key The key’s owner must also
Decide Held MCP Calls (mcp:decide) approve or deny a held agent tool call hold the agent-oversight permission (the roles that see Agents → Approvals)
Decide Access Requests (decide:access_requests) approve or reject an access request’s current stage be an approver of that stage, either assigned or through an active delegation

Both checks run on every call, not only when the key is created. If the owner loses the role, or is suspended, locked or leaves, the key stops deciding.

One key can’t both ask for a decision and make it. AtmanID refuses a key with mcp:authorize and mcp:decide together (your gateway would approve its own holds), and a key with write:access_requests and decide:access_requests together.

Decide a held MCP tool call

When AtmanID holds an agent’s call (POST /api/v1/mcp/authorize answered hold), the answer carries hold.id. To approve or deny it:

Terminal window
curl -X POST https://app.atmanid.com/api/v1/mcp/authorize/holds/hitl-eval-7f3a/decision \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"decision": "approve", "note": "Expected release PR", "category": "manual_verification"}'
{
"ver": 1,
"id": "hitl-eval-7f3a",
"status": "approved",
"decided_by": "Ana Approver",
"decided_at": "2026-10-30T14:02:11.000Z",
"approval_expires_at": "2026-10-30T15:02:11.000Z"
}
  • note is the reason, recorded with the decision.
  • category (from API version 1.42.0) says why the decision goes against AtmanID’s suggestion: approving a HIGH or CRITICAL hold, or denying a MEDIUM or LOW one. Use one of policy_exception, urgent_request, manual_verification or agent_error, the same reasons the console asks for. Any other value is 400 VALIDATION_ERROR.

Both are optional today, and nothing is refused without them. In a later API version, announced with its date before it takes effect, a decision on a HIGH or CRITICAL hold will require note, and a decision against the suggestion will require category. To be ready, send note with every decision and category with every approve: gateway holds are created at HIGH risk. Until then, the audit record of a decision without them names what was missing in new_state.reason_rule, so you can find the calls to change.

An approval lets the call through once, and only until approval_expires_at (your tenant’s approval window). The agent’s gateway sends the same call again and AtmanID allows it. A deny keeps the call denied.

You can decide a hold only while it is open:

  • 409 ALREADY_DECIDED: someone already decided it, or used the approval, or the approval’s window ran out. When two API calls decide the same hold at once, one lands and the other gets this error.
  • 409 HOLD_EXPIRED: the hold passed its deadline with no decision, so it counts as denied. The agent has to ask again.
  • 404 NOT_FOUND: no gateway hold in your tenant has that id.

The audit trail records AGENT_HITL_DECIDED (or AGENT_HITL_OVERRIDE when the decision goes against the system’s recommendation), with channel: api, the API key’s id and, when you sent one, the category as override_category.

Decide an access request

Terminal window
curl -X POST https://app.atmanid.com/api/v1/access-requests/0b6e7f4a-1c2d-4e5f-8a9b-0c1d2e3f4a5b/decision \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"decision": "APPROVE", "comments": "Needed for the Q4 close"}'
{
"ok": true,
"decision": "APPROVE",
"outcome": "Stage 1 APPROVED — advanced to stage 2 of 2",
"request_status": "PENDING",
"current_stage": 2,
"total_stages": 2,
"quorum": { "approved": 1, "required": 1, "met": true }
}

The call is one vote on the current stage, and it goes through the same checks as the console:

  • A REJECT needs comments or decision_reason.
  • Nobody approves their own request, or a request for themselves, including from a second account linked to the same person.
  • One vote per person per stage, and a different person at each stage.
  • When the entitlement’s reach is unknown and your tenant requires attestation, send "attested": true; without it the call fails with 422 ATTESTATION_REQUIRED.
  • On the last stage, the separation-of-duties re-check runs. A blocking conflict returns 409 with details.conflicts. When AtmanID can offer a time-boxed grant instead, details.safe_alternative describes it; send the decision again with "accept_safe_alternative": true to take it.
  • A stage that needs several approvals stays PENDING until it has them.

There is no administrator override by API. An administrator who isn’t an approver of the stage decides in the console, where the override is recorded as one.

request_status tells you where the request stands after your vote. The audit trail records APPROVAL_STAGE_APPROVED or APPROVAL_STAGE_REJECTED with channel: api, the API key’s id and the X-Request-Id of your call.

Errors

Every refusal uses the standard error shape. Switch on error.code; keep error.request_id for support.

{ "error": { "code": "RBAC_DENIED", "message": "Stage 1 is assigned to lee@acme.com — you are not authorized to decide this stage", "request_id": "req_01KQ…" } }

The full request and response schemas are in the API reference.

© AtmanID · Privacy