Skip to content

API Reference

← Documentation · ← 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

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