Skip to content

Build with AtmanID

Versioned API platform for identity governance. Mint a key, browse the contract, ship an integration in a single sitting.

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.

Read the changelog →

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.

See the contract →

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.

Try the quickstart →

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:

1. First-time integrator → start with curl

The 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.

2. Building a TypeScript / Node integration → use the SDK

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.

3. Looking up an endpoint → use the API Reference

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.

4. Hitting a specific integration pattern → use the cookbook

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.
  • The AtmanID app — at your tenant’s base URL, provided with your onboarding. Authenticated. Includes the Developer Console for API key / webhook / usage management.
  • 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

  • New to AtmanID overall? Read What is AtmanID? for the 5-minute conceptual overview before integrating.
  • Want to understand the data model you’ll be calling against? How AtmanID thinks about IAM covers the entitlement / role / certification model.
  • Building agent / non-human-identity integrations? Iris is the AI surface that helps developers reason about agent identities at scale.

© AtmanID · Privacy