Idempotency

Network calls fail halfway. Idempotency lets you retry a write without risking a duplicate — the same key replays the first result instead of performing the action twice.

How it works

Send an Idempotency-Key header (any unique string you choose — a UUID, or a natural key like signup-ada-001) on a supported POST:

curl https://api.atlas.dev/v1/users \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-ada-001" \
  -d '{"email_address":"ada@example.com"}'

• The first request with a given key performs the action and records the response.

• A retry with the same key returns the recorded response — the user is created once.

• Reusing a key with a different body is a conflict: 409 IDEMPOTENCY_CONFLICT.

Which endpoints honour it

Idempotency applies to creates and state-changing mutations that would be unsafe to repeat. Every such endpoint is marked idempotent in this reference — for example:

• POST /v1/users, PATCH /v1/users/:id, POST /v1/users/:id/ban, DELETE /v1/users/:id

• POST /v1/organizations, PATCH /v1/organizations/:id

• POST /v1/oauth_clients, POST /v1/sso_connections, POST /v1/scim_tokens

• POST /v1/user_imports, POST /v1/user_exports (bulk jobs)

GET and naturally-idempotent PUT/DELETE do not need a key.

With an SDK

The Node SDK takes the key as a trailing argument on the methods that support it:

await atlas.users.create({ email_address: 'ada@example.com' }, 'signup-ada-001');
await atlas.organizations.create({ name: 'Acme', slug: 'acme', created_by: 'user_2a' }, 'org-acme-001');

Other SDKs accept it as idempotency_key / idempotencyKey.

Choosing keys

Derive the key from the intent of the operation (the natural business key), not from a random per-attempt value — that way an automatic retry reuses the same key and collapses to one action.