JWT Tokens

Atom issues JWTs signed with ES256 (ECDSA P-256 + SHA-256). Tokens are short-lived (default 1 hour) and tied to a server-side session that can be revoked independently.

Claims

{
  "sub": "entity-uuid",
  "sid": "session-uuid",
  "tid": "tenant-uuid or null",
  "iat": 1700000000,
  "exp": 1700003600
}

The JWT header also carries a kid (Key ID) that identifies which signing key to use for verification:

{
  "alg": "ES256",
  "kid": "550e8400-e29b-41d4-a716-...",
  "typ": "JWT"
}

Session binding

Every JWT references a session row via the sid claim. On every token verification, Atom:

1. Decodes the JWT and extracts sid.
2. Looks up the session row.
3. Checks that revoked_at IS NULL and expires_at > now().

This means:

• Logout is instant — revoking the session immediately invalidates all tokens issued for that session, without waiting for JWT expiry.
• Status changes propagate — suspending an entity's session revokes the token; there is no window where a suspended entity holds a valid token beyond the check period.

Expiry

Default TTL is 3600 seconds (1 hour), configurable via JWT_EXPIRY_SECS. For long-running services that need persistent access, use API keys instead.

Refresh tokens

Set ATOM_REFRESH_TOKENS_ENABLED=true (requires ATOM_KEY_ENCRYPTION_KEY) to have login also return a long-lived opaque refresh token — an atom_rt_<id>_<secret> credential, verified the same way as access tokens (a KEK-keyed HMAC digest, never stored or logged in plaintext) but kept in its own table and never accepted by Bearer/API-key auth, gRPC, broker auth, or certificate enrollment.

mutation {
  refreshToken(input: { refreshToken: "atom_rt_..." }) {
    accessToken
    refreshToken
    accessTokenExpiresAt
    refreshTokenExpiresAt
  }
}

Send this request without an Authorization header — the refresh token itself is the credential, and the normal request wrapper would otherwise reject an expired JWT before this resolver runs (the same reason refreshSession, below, cannot recover from an already-expired token).

Each exchange consumes the presented token and returns a new access JWT plus a new refresh token for the same session; the previous refresh token stops working immediately. refreshTokenExpiresAt is the family's fixed absolute deadline — it never moves forward on rotation, so a session cannot be kept alive indefinitely by repeated refreshing. Presenting an already-consumed token is treated as token theft: it revokes the session and every token in its family, not just the one presented.

refreshSession (the older, JWT-authenticated session-extension mutation) is deprecated but unchanged, and still requires a currently valid access JWT.

Verification flow (Atom-internal)

1. Extract kid from the JWT header.
2. Look up the corresponding public key in the in-memory key store (primary or standby).
3. Verify the ES256 signature.
4. Validate exp.
5. Query the sessions table to confirm the session is not revoked or expired.

External verification

If your service holds a copy of Atom's public keys (fetched from GET /.well-known/jwks.json), it can verify the JWT signature locally without calling Atom. This proves:

• The token was issued by Atom.
• The token has not expired.

It does not prove:

• The session has not been revoked.
• The entity is still active.

For full authorization (including policy evaluation), always call POST /authz/check. External JWT verification is appropriate only for identity checks where revocation latency is acceptable.

See JWKS & Key Rotation for details on external verification setup.