Versioned
Semantic versioning on the contract itself. Our deprecation policy enforces a 6-month minimum window with standard RFC 8594/9745/8288 Sunset/Deprecation/Link headers. Every breaking change is announced in advance.
Three pillars
Versioned
Semantic versioning on the contract itself. Our deprecation policy enforces a 6-month minimum window with standard RFC 8594/9745/8288 Sunset/Deprecation/Link headers. Every breaking change is announced in advance.
Auditable
Every mutation produces an immutable audit row linked to the originating call by request_id. Cross-table forensic chain operational across all v1.* surfaces. An auditor can trace any workflow run to its audit row in two clicks.
GitOps-ready
NHI lifecycle (joiner / mover / leaver) exposed at /api/v1/agents with idempotency keys + managed_by ownership scoping. Two reference consumers in production: a GitHub Action and an MCP server.
Three paths in
Recent changes
Latest 3 spec versions. Full timeline in the changelog.
v1.12.0 — 2026-10-08
Contract changes since 1.11.0 — a new EXPIRED user status, stricter joiner name validation, total_pages always at least 1, and webhook behaviour and documentation corrections.
v1.11.0 — 2026-08-26
Audit API surfaces who — or what — performed each action: actor_type, delegated_by, confirmation_method, agent_session_id.
v1.10.0 — 2026-06-10
Dual agent ownership — a managing team (owner_group_name) distinct from the accountable individual, with team-aware offboarding.
Already a tenant?
Mint keys from your tenant dashboard
Sign in at your tenant’s base URL → Settings → Developer → API Keys → Create new key → pick scopes → copy the secret once, store it. The same console exposes Webhooks CRUD + per-key usage analytics.
The four entry paths
If you prefer prose to cards, pick the route that matches what you’re building:
curlThe first API call tutorial walks through authentication, your first GET /v1/users, parsing the response, and verifying the audit log entry. No SDK, no framework — just curl and the response body. ~10 minutes. Everything else builds on this.
The TypeScript SDK tutorial covers the same scenario with the TypeScript SDK (vendored source for pilot customers today; the @atmanid/sdk npm package is planned for v2): typed responses, retry on transient failures, structured errors, IDE autocomplete on every endpoint. ~10 minutes. Then read the SDK Reference for the full surface.
API Reference is the source of truth for HTTP semantics — paths, parameters, request bodies, response schemas, error codes. Backed by the OpenAPI spec generated from the API’s own schemas (live at $ATMANID_BASE_URL/api/v1/openapi; this site serves a copy refreshed with every API change). Interactive Scalar explorer embedded — try calls without leaving the page.
Common Patterns covers the integration patterns you’ll actually use in production: pagination, error handling, retry logic, rate limit handling, webhook signature verification, idempotency keys. If you’re hitting a specific shaped problem (“how do I retry on 429?”), this is the page.
Contract rules at a glance
A handful of rules hold across every /api/v1/* surface. Code against these and you won’t be surprised:
| Rule | What it means |
|---|---|
| Auth | Authorization: Bearer atman_… on every request. Not x-api-key. |
| Versioning | All paths under /api/v1/. Semver + 6-month deprecation, with Sunset/Deprecation headers. |
| Pagination | Lists return { data, total, page, limit, total_pages } — never a bare array. limit max 100. |
| Idempotency | Identity-creating endpoints require an idempotency_key body field (not a header) — same key within 24h returns the cached response. Retry safely with the same key. |
| Errors | { "error": { "code": "<STABLE_ENUM>", "message": "…", "request_id": "req_…", "details": { … } } } (details optional). Branch on code, never the message. |
| Audit correlation | Every response carries X-Request-Id; every mutation writes a tamper-evident audit row keyed to it. |
| Rate limits | Per API key by key tier (standard 60/min, partner 600/min). On 429 (RATE_LIMITED), honour Retry-After and retry idempotent calls with the same key — see Common patterns → Rate limits. |
Reference at a glance
| Need | Where |
|---|---|
| HTTP endpoint signatures | API Reference |
| Live OpenAPI spec (machine-readable) | $ATMANID_BASE_URL/api/v1/openapi |
| TypeScript SDK reference | SDK Reference |
| API changelog | Changelog |
| Webhook event types | Webhook events |
| Rate limit tiers | Common Patterns → Rate Limits |
| Error codes | API Reference → Errors |
Operating on your account (authenticated console)
The static documentation at docs.atmanid.com is intentionally read-only. For anything that requires your account context — minting API keys, configuring webhooks, viewing usage analytics, drilling into webhook delivery history — use the Developer Console inside the AtmanID app.
The split is deliberate: docs answer “how does this work?” The console answers “show me MY data and let me change it.” Different surfaces, different problems.
What goes where on the AtmanID surfaces
Three production surfaces, each with a clear job:
docs.atmanid.com (this site) — all static documentation. Concepts, guides, tutorials, reference, this developer landing. Public, no auth.atmanid.com — the product site. What AtmanID is, a product walkthrough, comparisons with other identity platforms, free early access (the design partner programme), and the trust centre (security, privacy and accessibility).Sign in to the app at your tenant’s base URL (provided with your onboarding). The in-app developer portal mirrors this docs site. If you find a broken link, email hello@atmanid.com.
Keep going
© AtmanID · Privacy