Requests & responses

Content type

Request and response bodies are JSON. Send Content-Type: application/json on any request with a body. The wire is snake_case and the SDKs mirror it exactly — they type the API rather than inventing a second dialect.

curl -X PATCH https://api.atlas.dev/v1/users/user_2a \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ada","public_metadata":{"plan":"pro"}}'

Object shapes

Most resources carry an object discriminator and a string id:

{
  "object": "user",
  "id": "user_2a…",
  "first_name": "Ada",
  "last_name": null,
  "public_metadata": { "plan": "pro" },
  "mfa_enabled": false,
  "banned": false,
  "created_at": 1757600000000,
  "updated_at": 1757600000000
}

• Ids are opaque. Prefixes (user_, org_, sess_, role_, perm_) are a readability aid, not a contract to parse.

• Timestamps are epoch milliseconds (integers), or null where a value has never been set (e.g. last_sign_in_at).

• Nullable fields are explicit — a field is present as null rather than omitted.

Metadata bags

Users and organizations carry free-form JSON metadata in up to three bags:

PATCH merges the bag you send; PUT …/metadata replaces the named bags wholesale.

Mutations & deletions

• POST creates, PATCH partially updates, PUT replaces, DELETE removes.

• Deletes return a minimal acknowledgement: { "object": "user", "id": "user_2a…", "deleted": true }.

• Some revocations return a small custom shape (e.g. { "object": "session", "id": "…", "status": "revoked" }).

Reading raw formats

A few routes return non-JSON when asked (e.g. SAML SP metadata XML is carried inside a JSON envelope with a metadata_xml string). The SDKs expose these as typed helpers.