API Reference
The AtmanID v1 REST API exposes 50 endpoint paths (63 operations) for programmatic access to identity, governance, and lifecycle workflows. The spec is generated from the API’s own schemas, so the contract and the code cannot drift; this site serves a copy at /openapi.json, refreshed with every API change.
Interactive explorer
Live OpenAPI 3.1 spec rendered with Scalar. Browse every endpoint, expand request/response schemas, and use the Try It panel to fire authenticated calls. Paste your API key into the auth box first — mint one from the Developer Console if you don’t have one.
The explorer on this page loads this site’s copy of the spec (/openapi.json), which is regenerated from the API’s schemas in the same change as any /api/v1 contract change. The live spec is always available from your tenant at $ATMANID_BASE_URL/api/v1/openapi.json.
Where else to find the spec
| Surface | URL | Purpose |
|---|---|---|
| Interactive explorer | $ATMANID_BASE_URL/api/v1/explorer |
The same Scalar explorer, served by your tenant, with try-it-now per endpoint |
| Raw OpenAPI 3.1 JSON | $ATMANID_BASE_URL/api/v1/openapi.json (also /api/v1/openapi, same content) |
Importable into Postman / Insomnia / Bruno / your tooling of choice |
| Changelog feed | $ATMANID_BASE_URL/api/v1/changelog.json |
{ current_version, total_versions, changelog[] } — type-tagged version history; poll it to detect breaking-change announcements |
| Current spec version | info.version in the spec, and the X-Api-Spec-Version header on the spec and changelog responses — see the changelog |
Bumps on every consumer-visible change |
Resource taxonomy
| Resource class | Endpoints | What it does |
|---|---|---|
| Users / Identities | users.list · users.get · users.entitlements · users.accessSnapshot · identities.list · accessRequests.{list,create,get} |
Read the identity directory (users; identities lists non-human identities), a user’s entitlements and point-in-time access, file access requests |
| Apps / Entitlements / Bundles | apps.list · entitlements.list · entitlements.get · bundles.{list,create,get,update,delete} |
App registry + entitlement catalog + role bundles |
| Identity Lifecycle (NHIs) | agents.{list,register,update,deactivate} |
Non-human identity (AI agents, service accounts) lifecycle |
| Identity Lifecycle (humans) | jml.{joiner,mover,leaver,status} |
Joiner / Mover / Leaver workflow triggers |
| Governance / Observability | audit.list · sodViolations.list · reachability.preview |
Audit trail, SoD policy violations, access reachability analysis |
| Webhooks | webhooks.{list,create,get,update,delete,test} |
Outbound event delivery to your systems |
| Connectors | github.overview · github.discover |
GitHub connector — list workflows + discover NHIs from repo activity |
| Workflow templates | workflowTemplates.{list,apply,get,delete} |
GitOps-managed approval workflow templates (apiVersion: atmanid.com/v1) |
Authentication
API key. Every /api/v1/* endpoint authenticates with an API key: Authorization: Bearer atman_<key>. Keys carry scopes (for example read:users, write:nhi, write:jml, read:audit_logs); each endpoint’s required scope is documented in the explorer. Mint keys in the AtmanID app under Settings → API Keys (also reachable from Settings → Developer Portal). Browser sessions are not accepted on /api/v1/*.
For mutating endpoints, a matching scope is necessary but not sufficient: the key owner’s current role permissions are also checked on every request, so revoking a permission from the owner’s role takes effect for their keys immediately (403 RBAC_DENIED). A key can also be restricted to an IP allowlist.
Versioning + deprecation
The spec version (info.version) follows semantic versioning:
- Major bumps (e.g., 1.x.x → 2.0.0) — breaking changes, 6-month deprecation window required
- Minor bumps (1.8.0 → 1.9.0) — additive changes (new endpoints, new optional fields)
- Patch bumps (1.9.0 → 1.9.1) — bug fixes, contract-preserving
Deprecated endpoints emit Sunset: and Deprecation: HTTP response headers (RFC 8594/9745) with the removal date. Subscribe to $ATMANID_BASE_URL/api/v1/changelog.json to detect deprecation announcements automatically.
Rate limits
Requests are limited per API key by the key’s tier, chosen when the key is created: standard 60 requests/minute, partner 600 requests/minute. A per-client limit of 60 requests/minute per endpoint also applies before authentication.
A limited call returns 429 with error code RATE_LIMITED and a Retry-After header (seconds) per RFC 9110. See Common patterns for handling these correctly.
Errors
Every non-2xx response from /api/v1/* uses one envelope:
{ "error": { "code": "RBAC_DENIED", "message": "Insufficient scopes", "request_id": "req_01KQ...", "details": { "required": ["write:nhi"], "missing": ["write:nhi"] } }}Branch on error.code; message wording may change. details is optional and specific to the code. Codes are additive — existing codes are never removed or repurposed. The codes you will see most often:
| Status | error.code |
Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR |
Body or query failed validation — see details |
| 400 | INVALID_JSON |
Body is not valid JSON |
| 401 | UNAUTHENTICATED |
Missing, malformed, revoked or expired API key |
| 403 | RBAC_DENIED |
Key lacks the scope, the key owner’s role lacks the permission, or the request IP is outside the key’s allowlist |
| 404 | NOT_FOUND (or a resource-specific code such as USER_NOT_FOUND) |
Resource absent or not visible to the caller |
| 409 | CONFLICT, AGENT_NAME_CONFLICT, AGENT_ALREADY_EXISTS, USER_ALREADY_EXISTS, AGENT_DEPROVISIONED, quota codes |
Conflicts with existing state |
| 409 | IDEMPOTENCY_IN_PROGRESS |
A request with this idempotency_key is still being processed (agent register, update and deactivate). Retry once it has finished |
| 422 | UNPROCESSABLE, SSRF_BLOCKED |
Well-formed but semantically invalid (for example a webhook URL that deliveries would refuse) |
| 422 | PERSON_DEPARTED |
The person the call names has left the organisation, so nothing was created. On POST /access-requests: the target is Inactive, Expired, Terminated or in a status the lifecycle does not know; details.target_status says which |
| 422 | USER_DEPROVISIONED |
POST /access-requests for a Deprovisioned target; nothing was created. details.target_status is DEPROVISIONED |
| 422 | IDEMPOTENCY_KEY_REUSED |
The idempotency_key was already used within 24 hours for a different request body (agent register, update and deactivate); nothing was done. Send a new key for a new request |
| 429 | RATE_LIMITED |
Rate limit hit — honour Retry-After |
| 500 / 503 | INTERNAL_ERROR |
Server fault; no internal detail is returned — quote request_id to support |
The ErrorCode schema in the spec currently lists an earlier seed set of codes (for example VALIDATION_FAILED, UNAUTHORIZED, FORBIDDEN, RATE_LIMIT_EXCEEDED); the codes in the table above are the ones the API actually returns.
Where to go next
- First API call tutorial — minimal viable curl walkthrough (get key, make request, parse response) in 10 minutes
- SDK Reference — the TypeScript SDK (install, types, every method documented)
- First SDK script tutorial — same shape as First API call but via the SDK
- Common patterns tutorial — pagination, error handling, retries, webhook verification
Spec sync (operator note)
The OpenAPI spec is generated from Zod schemas in the API. This docs site serves an exported copy at /openapi.json; it is re-exported in the same change as any /api/v1 contract change, and CI fails if the copy is stale. Your tenant’s /api/v1/openapi.json always reflects the deployed contract.
© AtmanID · Privacy