Skip to content

Run certification campaigns and export the decision log by API

Certification campaigns run in the console (launch a campaign). This API runs the same campaigns from outside it: a quarterly job launches them, reviewers decide items from another tool, and the evidence file goes straight into your audit folder. The same API exports the MCP gateway’s decisions on agents’ tool calls.

Before you start

An API key acts as the person who created it, and that person needs the matching permission in the console, checked on every call. A key whose owner is suspended or has left stops working.

Scope Lets the key The key’s owner needs
read:certifications list campaigns and their items; export evidence to see campaigns (and, for evidence, to export them)
write:certifications launch a campaign or save a draft to launch campaigns
decide:certifications certify, revoke or escalate an item to review
read:mcp_decisions export the gateway’s decision log to see MCP Gateway events

Launching and deciding are high impact, so a key with those scopes waits for approval before it is issued. An owner who reviews items but doesn’t run campaigns (a manager, say) sees only the campaigns they review in, and only their own items.

Launch a campaign

Terminal window
curl -X POST https://app.atmanid.com/api/v1/certifications/campaigns \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"name": "Q4 manager review", "campaign_type": "manager_certification", "deadline": "2026-12-15",
"min_risk": "MEDIUM", "exclude_recently_certified_days": 30}'
{ "id": "0b6e7f4a-…", "status": "ACTIVE", "campaign_type": "manager_certification", "reviews_queued": 412, "reviews_skipped_no_reviewer": 0, "wave_count": null }

The body takes the console’s launch options: scoping (min_risk, exclude_recently_certified_days, granted_before_days, scope_criteria or scope_query, incremental_only), stages for multi-stage review, wave_size to release reviewers in waves, and non_response_action for items nobody decides. Send "save_as_draft": true to store it without notifying anyone. Reviewers are notified when the campaign launches.

GET /api/v1/certifications/campaigns lists campaigns 25 per page (up to 100), newest first, with progress as a percentage. Filter with status (one value or several, comma-separated) and sort with sort_by (created_at, deadline, name, progress, urgency). GET …/campaigns/{id} adds the item counts by status, and GET …/campaigns/{id}/reviews lists the items, which you can filter by status or reviewer_id.

Decide an item

Terminal window
curl -X POST https://app.atmanid.com/api/v1/certifications/reviews/5c1d…/decision \
-H "Authorization: Bearer $ATMANID_KEY" -H "Content-Type: application/json" \
-d '{"decision": "REVOKE", "note": "Moved to the platform team in October"}'

decision is CERTIFY, REVOKE or ESCALATE. The checks are the console’s:

  • The item is decided on what it covers in AtmanID; nothing in the body can change the subject.
  • An item assigned to someone else can be decided only by an owner allowed to override, with a note of at least 20 characters: 422 JUSTIFICATION_REQUIRED otherwise. Your policy may also require a note on some decisions.
  • Nobody certifies their own access: 403 SELF_CERTIFICATION_FORBIDDEN.
  • A cancelled campaign takes no decisions: 409 CAMPAIGN_CANCELLED.
  • REVOKE works only where one decision can remove the access; otherwise 400.

Each decision is recorded with its decision trace, as in the console, plus a CERT_REVIEW_DECIDED_VIA_API record that carries your API key’s id. A REVOKE that the blast-radius check intercepts answers 202 with "decided": false: nothing changed, and the item waits for review in the console.

Export the evidence

Terminal window
curl -o q4-evidence.csv https://app.atmanid.com/api/v1/certifications/campaigns/0b6e7f4a-…/evidence?status=REVOKED \
-H "Authorization: Bearer $ATMANID_KEY"

This is the console’s export: reviewer, subject, application, entitlement, risk, decision, when, how long, delegations and escalation notes. Filter with status (ALL by default) or reviewer_id. Every export is recorded (CERT_CAMPAIGN_EXPORTED); if the record can’t be written, no file is sent.

Export the MCP gateway decision log

Terminal window
curl "https://app.atmanid.com/api/v1/mcp/decisions?since=2026-10-29T00:00:00Z&until=2026-10-30T00:00:00Z&decision=hold&limit=100" \
-H "Authorization: Bearer $ATMANID_KEY"

Each record gives the agent, server, tool and decision. decision is allow, deny, hold (waiting for a person’s approval, under enforce), would_deny (shadow) or bypass. Records also carry the deny reason, the intent policy that fired, inspection flags, status, latency, and your gateway’s name and decision_id when the decision was made for it. Request payloads are never included.

since and until are required, and a window can be at most 31 days. Keep both fixed while you page, so new decisions can’t shift the pages. Filter by decision, agent_id, server_id, tool, deny_reason or caller_gateway. For a SIEM, page through one window, then move it forward.

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

© AtmanID · Privacy