Sessions and tokens

Every endpoint is relative to the environment's issuer, https://auth.axiomcore.dev/<project_id>/<environment_id>. The examples set it once:

ISSUER="https://auth.axiomcore.dev/PROJECT_ID/ENVIRONMENT_ID"

Replace PROJECT_ID and ENVIRONMENT_ID with the lowercase UUIDs of your project and environment.

Request rules

• Bodies are strict JSON: unknown fields and duplicate keys are refused with AXAUTH_INVALID_REQUEST. Bodies are at most 16 KiB (32 KiB for exchange).
• Token responses carry Cache-Control: no-store.
• Errors are {"error":{"code":"AXAUTH_..."}}. 429 and 503 responses carry Retry-After.
• A request with an Origin header is answered only when the origin is in the environment's allowed origins; otherwise 403 AXAUTH_ORIGIN. Requests without Origin are accepted. No cookies are set.
• An unknown project or environment, or an environment where authentication is not enabled or not ready, answers 404 AXAUTH_NOT_FOUND.

Endpoints

? marks an optional field. audience selects one of the environment's configured audiences (default the first, which is <issuer>/api unless the owner changed it). tenant selects an organization the user is an active member of; see Roles and permissions.

Token response

{
  "access_token": "<compact JWS>",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "axr1_...",
  "refresh_expires_at": "2026-11-01T10:00:00Z",
  "session": { "id": "<uuid>", "absolute_expires_at": "2026-11-24T10:00:00Z", "tenant": null },
  "user": { "id": "<uuid>", "kind": "password", "email": "user@example.com" }
}

expires_in is in seconds. refresh_expires_at is the time after which the refresh token can no longer be used: the earlier of the idle and absolute session expiry. user.kind is password or external; email is present for password users only.

Sign up and sign in

curl -sS -X POST "$ISSUER/v1/signup" \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"a long passphrase"}'

Signup answers 201 with tokens, 409 AXAUTH_ACCOUNT_EXISTS for a taken address, and 403 AXAUTH_SIGNUP_DISABLED while signup is closed (the default). Sign-in uses the same body at /v1/sign-in/password and answers 200.

Passwords are 8 to 128 characters after Unicode normalization, at most 512 bytes of UTF-8, with no control characters, and must differ from the email address. There are no composition rules. Other passwords get 400 AXAUTH_WEAK_PASSWORD. Passwords are stored as Argon2id hashes.

Sign-in is enumeration-safe: an unknown email, a wrong password and an external user without a password all get the same 401 AXAUTH_INVALID_CREDENTIALS and the same work. 403 AXAUTH_USER_DISABLED (a banned user) is returned only after a correct password.

Refresh

curl -sS -X POST "$ISSUER/v1/token/refresh" \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"axr1_..."}'

Refresh tokens are one-time. A refresh does one of three things:

Two concurrent refreshes with one token commit at most one rotation; the loser counts as reuse and ends the session. Make one refresh at a time per session, and store the new refresh token before using it. There is no grace window, so a rotation response lost in transit also ends the session: sign in again.

503 AXAUTH_UNAVAILABLE means nothing changed: retry later with the same refresh token. In the rare case where Axiom cannot tell whether a rotation committed, the retry counts as reuse and the user signs in again.

Log out

Logout never ends an access token that was already issued; it expires on its own (see Revocation bounds). Logout and logout everywhere are never refused for quota.

Access tokens

An access token is a compact JWS of at most 8 KiB, signed with Ed25519. Its header is exactly:

{"alg":"EdDSA","typ":"at+jwt","kid":"<kid>"}

Tokens carry no scope, email, name or custom claims. To verify them, see Verify access tokens.

Discovery, JWKS and epoch

These documents are public, are not rate limited and never wake your database. They are served while the environment has signing keys, even when its database is suspended, and answer 404 only when it has none.

The discovery document is not an OpenID provider configuration: it names only the keys, the epoch and the algorithm.

• Keys. The JWKS holds at most 3 keys, the signing key first. A new key is published at least 10 minutes before it signs. A replaced key stays published until the tokens it signed have expired. Keys are replaced automatically before they are 180 days old. axiom_keys_rev increases whenever the published set changes.
• Epoch. The epoch increases when a project owner ends every session of the environment or retires a key for cause. Tokens carry the epoch they were issued in. keys_rev in the epoch response says which key set is current; emergency is true when that key set came from retiring a key for cause.

Revocation bounds

How long an access token that was already issued keeps working. "TTL" is the configured access token lifetime (Free default 15 minutes, Pro default 5 minutes, maximum 15 minutes). The epoch bound is 65 seconds (the issuer's 5-second snapshot plus 60 seconds) while the issuer is reachable after the server's first successful fetch; otherwise until exp; requests are refused before the first fetch. The Axiom server column applies to the axiomAuth verifier, which is Coming soon.

Rate limits

IPv4 addresses count individually; IPv6 addresses count per /64. Limits answer 429 AXAUTH_RATE_LIMITED with Retry-After.

Error codes

Next steps

• Put roles and permissions in tokens
• Verify access tokens in your backend