Agent integration prompt
AtmanID is an agent-native platform, so the fastest way to integrate is to let your coding agent do it. Paste the block below into your agent; it contains every canonical URL, header, and contract rule needed to write a correct integration in one pass.
The prompt
# AtmanID v1 integration β do this exactly
You are integrating AtmanID (AI-native Identity & Access Management) into <MY_STACK>.Every URL, header, and enum below is canonical β do not paraphrase or "improve" them.
## 1. Get an API key- In the AtmanID app: Settings β Developer β API Keys β Create new key.- Pick least-privilege scopes (e.g. read:users, write:nhi, write:jml).- The secret is shown ONCE and starts with `atman_`. Store it as ATMANID_API_KEY.
## 2. Base URL + auth- Base URL: your AtmanID tenant's base URL (provided with your onboarding). Store it as ATMANID_BASE_URL and build every request from it.- All API paths are under /api/v1/.- Auth header on EVERY request: Authorization: Bearer <ATMANID_API_KEY>- Always send: Accept: application/json
## 3. First read (verify auth works)GET /api/v1/usersResponse is the standard paginated envelope β code against this shape everywhere: { "data": [ ... ], "total": N, "page": 1, "limit": 25, "total_pages": M }Never assume a bare array. Never assume more than `limit` rows per page; paginate with ?page= & ?limit= (max 100).
## 4. Create a governed identityHumans and AI agents share the same Joiner/Mover/Leaver primitives.- Human: POST /api/v1/jml/joiner (NOT /api/v1/users β that endpoint is read-only)- AI agent / non-human identity: POST /api/v1/agentsScopes: POST /api/v1/agents needs write:nhi; POST /api/v1/jml/joiner needs write:jml.Headers on ALL mutations (POST/PATCH/DELETE): Authorization: Bearer <ATMANID_API_KEY> Content-Type: application/jsonIdempotency is a BODY FIELD, not a header: every create body REQUIRES`idempotency_key` (a fresh UUID per logical operation). The same key within24h returns the cached response instead of creating a duplicate.Example body for an agent (required: idempotency_key, name, type, owner_team, owner_email): { "idempotency_key": "<uuid>", "name": "ci-deploy-bot", "type": "ci-automation", "owner_team": "platform-eng", "owner_email": "dev.torres@example.com", "environment": "Production", "managed_by": "platform-eng-gitops" }`managed_by` is an optional ownership TAG (a workflow/team label for GitOpsscoping), not a user id.Example body for a human: { "idempotency_key": "<uuid>", "email": "sarah.chen@example.com", "first_name": "Sarah", "last_name": "Chen", "identity_type": "employee" }On success you get 201 with the new identity's id and status (an agent starts inPENDING_REVIEW; a joiner can also return 202 when it is accepted for later processing).Replaying the same idempotency_key returns 200 with `cached: true`.
## 5. Audit correlation (this is the whole point)- Every response carries an X-Request-Id header.- Every mutation writes a tamper-evident, hash-chained audit row.- The audit row is correlated to your call by that same request id.- To prove an action happened: capture X-Request-Id from the response, then look the action up in the audit trail (see /reference/api/ β audit endpoints). Do not treat a 2xx as proof on its own β confirm the audit row when the operation is compliance-relevant.
## 6. Errors- Error responses use a stable shape: { "error": { "code": "<STABLE_ENUM>", "message": "<human text>", "request_id": "req_...", "details": { ... } } } (`details` is optional.)- Branch on error.code (additive, never repurposed) β NOT on the message string.- Handle 400 (VALIDATION_ERROR / INVALID_JSON), 401 (UNAUTHENTICATED β bad/missing key), 403 (RBAC_DENIED β missing scope, or the key owner's role lacks the permission), 404, 409 (name/state conflict), 422 (semantically invalid), 429 (RATE_LIMITED).
## 7. Rate limits- Requests are rate limited per API key by key tier (standard 60/min, partner 600/min). On 429, read the Retry-After header and back off; retry creates with the SAME `idempotency_key` body field. See /tutorials/common-patterns/#rate-limit-handling.
## 8. Webhooks (if you consume events)- Register a destination + subscribe to events in the Developer Console.- VERIFY the webhook signature before trusting any payload β see /tutorials/common-patterns/#webhook-signature-verification for the exact algorithm.
## 9. Hard rules β do not change- Auth is `Authorization: Bearer atman_...` (NOT x-api-key).- All paths are versioned under /api/v1/ β never call unversioned paths.- Creates REQUIRE an `idempotency_key` BODY field (NOT an Idempotency-Key header).- Human creation is POST /api/v1/jml/joiner (NOT POST /api/v1/users).- Pagination envelope is { data, total, page, limit, total_pages } β never a bare array.- Branch on error.code, never on error.message.- Capture X-Request-Id and verify the audit row for compliance-relevant writes.
## 10. Now buildBased on <MY_STACK>:1. A typed API client (auth header + JSON + error-code handling + 429 retry reusing `idempotency_key`).2. The create-identity call (joiner or agent) with idempotency.3. A function that captures X-Request-Id and verifies the audit row.4. A webhook receiver with signature verification (if events are used).When unsure, fetch https://docs.atmanid.com/llms-full.txt for the full corpus.Prefer the SDK or the raw API?
Best for Node/TypeScript apps. Typed responses, retries, structured errors, and IDE autocomplete on every endpoint β fewer ways to get the contract wrong.
Pilot customers receive the SDK source today and vendor it into their project; the standalone @atmanid/sdk npm package ships with v2. See First SDK script for setup and the SDK Reference.
Best for non-Node stacks, server-to-server jobs, batch processing, or full control over transport. Everything is plain HTTP + JSON.
Start with First API call and the API Reference.
Which one for your situation?
| Question | Use the SDK | Use the raw REST API |
|---|---|---|
| Node / TypeScript app? | β Yes | Works, but you give up types |
| Non-Node stack (Python, Go, Rubyβ¦)? | β | β Yes |
| Want typed responses + autocomplete? | β Yes | β |
| Batch / server-to-server jobs? | Fine | β Yes |
| Building a coding-agent integration? | Either β paste the prompt above | Either β paste the prompt above |
| Need the absolute thinnest dependency? | β | β Yes |
Integration surfaces at a glance
| Surface | What it is | Status | Best for |
|---|---|---|---|
| REST API | Versioned HTTP + JSON under /api/v1/ |
β Live | Any language, full control |
| TypeScript SDK | Typed client (vendored source for pilot customers; @atmanid/sdk npm package planned for v2) |
β Live (vendored) | Node / TypeScript apps |
| GitHub Action | atmanid/workflow-sync GitOps consumer |
β Live | Manifest-driven lifecycle in CI |
| MCP server | Model Context Protocol reference consumer | β Live | Agent / LLM tool-calling integrations |
llms.txt / llms-full.txt |
Full docs corpus for LLM ingestion | β Live | Feeding an agent the whole product |
Next steps
- First API call β the same flow by hand in ~10 minutes.
- Common patterns β pagination, retries, 429 handling, idempotency, webhook signatures.
- API Reference β the OpenAPI 3.1 source of truth with a try-it-now explorer.
Β© AtmanID Β· Privacy