Skip to content

Cookie, Session, And Token Reference

Seamless Auth uses signed browser cookies at the app boundary and bearer tokens at the auth API boundary.

This page explains which cookies exist, what they carry, when sessions are created or rotated, and which token types are currently used by seamless-auth-api, @seamless-auth/express, and @seamless-auth/core.


Browser
-> signed HttpOnly cookies on your app/API domain
-> your backend with @seamless-auth/express
-> bearer tokens forwarded to seamless-auth-api

The browser should not need to read Seamless Auth tokens directly. The Express adapter signs local cookies with cookieSecret, then uses the token values inside those cookies when it forwards requests to seamless-auth-api.


createSeamlessAuthServer(...) defaults to these cookie names.

Cookie Default name Purpose
Access cookie seamless-access Authenticated app/API session
Refresh cookie seamless-refresh Opaque refresh-token storage for session rotation
Registration cookie seamless-ephemeral In-progress registration, OTP, and passkey registration
Pre-auth cookie seamless-ephemeral In-progress login, OTP, magic-link, and passkey login

Registration and pre-auth use the same default cookie name. You can override them separately if your application needs distinct cookies.

createSeamlessAuthServer({
authServerUrl: process.env.AUTH_SERVER_URL!,
cookieSecret: process.env.COOKIE_SIGNING_KEY!,
serviceSecret: process.env.API_SERVICE_TOKEN!,
audience: process.env.AUTH_SERVER_URL!,
accessCookieName: 'sa_access',
refreshCookieName: 'sa_refresh',
registrationCookieName: 'sa_registration',
preAuthCookieName: 'sa_pre_auth',
})

The Express adapter sets cookies as:

Attribute Current behavior
httpOnly Always true
path /
domain cookieDomain option, if provided
maxAge Token TTL returned by the auth API
secure true when NODE_ENV=production
sameSite none in production, lax outside production

For cross-site browser deployments, use HTTPS and set a cookie domain that matches the frontend/API shape you are deploying.


The access cookie is a local HS256 JWT signed by the Express adapter with cookieSecret.

It stores enough information for the adapter to forward authenticated requests and for your backend to perform route checks.

Field Meaning
sub User ID
sessionId Current auth API session ID
token RS256 access token issued by seamless-auth-api
roles User global roles
email User email
phone User phone
organizationId Active organization ID, when selected

requireAuth({ cookieSecret }) verifies this signed cookie and attaches req.user.

app.get('/api/me', requireAuth({ cookieSecret }), (req, res) => {
res.json({ user: req.user })
})

req.user contains:

type SeamlessAuthUser = {
id: string
sub: string
roles: string[]
email: string
phone: string
iat?: number
exp?: number
}

requireAuth(...) does not call the auth API and does not rotate refresh tokens. It only verifies the local access cookie. Route-specific refresh behavior happens in the adapter middleware mounted inside createSeamlessAuthServer(...).


The refresh cookie is also a local HS256 JWT signed with cookieSecret.

It contains:

Field Meaning
sub User ID
refreshToken Opaque refresh token issued by seamless-auth-api

The opaque refresh token is stored server-side as:

  • refreshTokenHash: bcrypt hash
  • refreshTokenLookup: HMAC lookup fingerprint derived from REFRESH_TOKEN_LOOKUP_SECRET or API_SERVICE_TOKEN

The raw refresh token is not stored in the database.


Registration and login flows use short-lived ephemeral cookies before a full access session exists.

Flow Cookie Carries
Start registration registration cookie sub, ephemeral token
Verify registration OTP registration cookie forwarded bearer identity
Register passkey registration cookie forwarded bearer identity
Start login pre-auth cookie sub, ephemeral token
Login OTP/magic link/passkey continuation pre-auth cookie forwarded bearer identity

The auth API signs ephemeral tokens as RS256 JWTs with typ: "ephemeral" and a five-minute expiration.


Token Format Used for
Access token RS256 JWT Authenticated auth API requests
Ephemeral token RS256 JWT In-progress login/registration steps
Refresh token Opaque random string Refresh-token rotation
Service token Adapter-created token Trusted service-to-service refresh and delivery calls

Access tokens include:

Claim Meaning
sub User ID
sid Session ID
iss Auth API issuer
typ access
roles User roles
org_id Active organization ID, when selected
aud Auth API issuer (its ISSUER)

The adapters verify iss against authServerIssuer, which defaults to authServerUrl, and aud against audience. Both claims carry the auth API’s ISSUER, so when the adapter reaches the auth server at another URL (a host-run app against the local Docker stack calls http://localhost:5312 while the server signs as http://auth:5312), set authServerIssuer and audience to the issuer. See Server SDKs: Auth server issuer.

Refresh tokens are currently opaque random strings. The auth API refresh endpoint expects the raw opaque refresh token in the bearer header, not the access JWT.


The auth API stores sessions in the sessions table.

Field Meaning
id Session ID
userId Owning user
infraId App or infrastructure identifier
organizationId Active organization for the session
mode Currently server
refreshTokenHash Bcrypt hash of the opaque refresh token
refreshTokenLookup HMAC lookup fingerprint
lastUsedAt Last refresh/use timestamp
expiresAt Absolute session expiry
idleExpiresAt Idle session expiry
stepUpVerifiedAt Last fresh step-up verification
stepUpMethod webauthn or totp
replacedBySessionId Refresh rotation successor
revokedAt Revocation timestamp
revokedReason Revocation reason

Current session records use a one-day absolute lifetime and one-day idle timeout in the auth API. Access and refresh cookie TTLs are controlled separately by system config.


On successful refresh:

  1. the adapter verifies the refresh cookie with cookieSecret
  2. the adapter sends the raw refresh token to POST /refresh
  3. the auth API finds the active session by refreshTokenLookup
  4. the auth API creates a new session record
  5. the old session gets replacedBySessionId
  6. the auth API returns a new access token and opaque refresh token
  7. the adapter sets fresh access and refresh cookies

If an already-rotated refresh token is reused, the auth API treats it as suspicious and revokes the session chain.

The core refresh helper deduplicates simultaneous refreshes briefly so parallel browser requests do not normally race each other into token reuse.


createSeamlessAuthServer(...) installs ensureCookies(...) for routes it owns under /auth.

For those adapter routes, if a required access cookie is missing or does not contain the upstream access token, and a valid refresh cookie exists, the adapter attempts refresh and sets new cookies.

This applies to adapter-owned auth routes such as:

  • /auth/users/me
  • /auth/logout
  • /auth/organizations/*
  • /auth/step-up/*
  • /auth/admin/*
  • /auth/internal/*
  • /auth/system-config/*

For your own application routes, requireAuth(...) only verifies the access cookie. If you need refresh before custom app routes, call an adapter-owned route such as /auth/users/me from the client before retrying, or implement an explicit server-side refresh strategy with @seamless-auth/core.


Current logout behavior:

Route Meaning
DELETE /auth/logout Revoke current session and clear auth cookies
DELETE /auth/logout/all Revoke all user sessions and clear auth cookies

Session revocation sets revokedAt and revokedReason. Admin session routes can revoke individual sessions or all sessions for a user.


seamless-auth-api signs access and ephemeral JWTs with RS256.

In development (any NODE_ENV other than production):

  • the API creates an RSA key pair at startup, before it starts listening, so /.well-known/jwks.json serves the dev public key from the first request
  • keys live in SEAMLESS_DEV_KEYS_DIR, default ./keys/dev relative to the working directory (/app/keys/dev in the image)
  • the key ID is dev- followed by the first 16 characters of the key’s RFC 7638 JWK thumbprint (base64url), for example dev-xXoIGRrgENKN6lCF
  • a regenerated key gets a new key ID, so adapters that cache the JWKS refetch it instead of verifying against a stale key
  • only private.pem has to survive a restart; the public key is derived from it. The API’s bundled docker-compose.yml keeps /app/keys on a dev-keys volume so a recreated container keeps its key
  • the Docker stack from seamless init mounts a named auth-keys volume at /app/keys on the auth service once the CLI release with fells-code/seamless-cli#228 ships. With --auth=local the auth source directory is bind-mounted over /app, so the keys already live on the host
  • if no key can be read, the endpoint answers 200 { "keys": [] } and logs why

The adapters’ jwksKid option (default dev-main) is a different value: it sets the kid header on the HS256 service tokens an adapter sends to the API, and it does not need to match the API’s dev signing key ID.

In production:

  • SEAMLESS_JWKS_ACTIVE_KID identifies the active signing key
  • SEAMLESS_JWKS_KEY_<kid>_PRIVATE contains the private key PEM for the active key
  • SEAMLESS_JWKS_PUBLIC_KEYS contains public keys served by /.well-known/jwks.json

The Express/core handlers verify signed auth API responses against the auth API JWKS before setting local cookies.


Mistake Fix
Using the access JWT as the refresh bearer token Use the opaque refresh token from the refresh cookie payload
Expecting requireAuth(...) to refresh sessions Let /auth adapter routes refresh, or add explicit refresh handling
Changing cookie names in the adapter but not in requireAuth(...) Pass the same cookieName to requireAuth(...)
Calling raw auth API routes from browser code Call your backend adapter routes unless you are building a custom server adapter
Rotating JWKS private keys without publishing public keys Keep SEAMLESS_JWKS_ACTIVE_KID, private key, and SEAMLESS_JWKS_PUBLIC_KEYS aligned