API overview

Agent Access Manager exposes two REST planes on the same host. Everything the dashboard does goes through the Admin API, so anything you can click, you can script.

Plane	Base path	Who calls it	Auth
Gateway API	`/v1`	Applications and agents	Virtual key
Admin API	`/admin`	Admins, dashboards, automation	SSO session, OIDC Bearer, or Basic

All examples in this reference use https://aam.example.com as the host. Requests and responses are JSON (Content-Type: application/json) unless noted; streaming responses are Server-Sent Events.

Authentication

Data plane (`/v1`)

Present a virtual key either way — both are accepted on every surface, so stock clients work by changing only their base URL:

TEXT

Authorization: Bearer sk-your-virtual-key     # OpenAI SDKs, Codex, Claude Code
x-api-key: sk-your-virtual-key                # Anthropic SDKs and tools

Admin plane (`/admin`)

Three additive methods (see Enterprise SSO):

Command

# Break-glass Basic admin (bootstrap; scripts)
curl -u admin:PASSWORD https://aam.example.com/admin/providers

# OIDC Bearer token from your IdP (requires the realm role and audience)
curl -H "Authorization: Bearer eyJ..." https://aam.example.com/admin/providers

Browser sessions (the dashboard) use cookie-based sessions with CSRF protection — relevant only if you are building UI against the API.

Admin endpoints are org-scoped. An org member is locked to their own org automatically. A platform admin picks the org per request: an orgId field in create bodies, an ?orgId= query parameter on reads. Endpoints marked (org-scoped) in the Admin API follow this pattern.

Errors

The data plane relays upstream error bodies and status codes verbatim wherever possible, so SDK error handling keeps working. Gateway-generated errors use the OpenAI error shape:

JSON

{
  "error": {
    "type": "content_blocked",
    "message": "Request blocked by guardrail policy (category: SECRET)"
  }
}

Status codes you will engineer around:

Code	Meaning	Notes
`400`	Malformed request	Validation failure on a body field
`401`	Missing/invalid credential	Unknown, expired, or revoked key; bad admin token or audience
`403`	Denied	Insufficient capability on `/admin`; `content_blocked` by a guardrail on `/v1`
`404`	Not found	Unknown provider, deployment, or entity
`409`	Conflict / ceiling	Duplicate name; provider, deployment, or key-count cap reached
`429`	Over budget or rate-limited	Rate limits include a `Retry-After` header; budget denials happen pre-call
`5xx`	Upstream or gateway failure	Transient upstream errors are retried and failed over before you see one

On a stream, an error after the 200 is committed arrives as a terminal SSE error event; the audit record still captures the real outcome.

Pagination

List endpoints that can grow unbounded (keys, audit calls, delivery logs) are paginated with page/size query parameters and return standard page metadata. Small, per-org lists (providers, deployments, budgets on a scope) return plain arrays.

OpenAPI

The full, versioned OpenAPI spec of the Admin API is served by the running product:

GET/admin/api-docs

It is the source the dashboard's own typed client is generated from, so it is always accurate for the version you are running — use it to generate clients or diff between releases.