Skip to content

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/users
Response 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 identity
Humans 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/agents
Scopes: 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/json
Idempotency is a BODY FIELD, not a header: every create body REQUIRES
`idempotency_key` (a fresh UUID per logical operation). The same key within
24h 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 GitOps
scoping), 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 in
PENDING_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 build
Based 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.

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