JWT token lifecycle: refresh, rotate, and terminate sessions

Understand Alphabet’s access and refresh token lifecycle, how to rotate tokens, handle expiry, and terminate sessions across devices.

Alphabet issues two types of token on every successful login: a short-lived JWT access token and a longer-lived refresh token. The access token authorizes individual API requests; the refresh token is used only to obtain a new access token when the current one expires. Understanding this lifecycle — and building your client to handle it automatically — is the key to a reliable Alphabet integration.

Token lifetimes

Token	Default lifetime	Configuration key
Access token	15 minutes	Jwt.AccessTokenExpiryMinutes
Refresh token	7 days	Jwt.RefreshTokenExpiryDays
MFA token	5 minutes	Jwt.MfaTokenExpiryMinutes

These values are set in appsettings.json under the Jwt section. Adjust them to match your security requirements.

Using the access token

Include the access token in the Authorization header of every request to a protected endpoint:

Authorization: Bearer <accessToken>

The token is a signed HS256 JWT issued by Alphabet for the audience Alphabet.Clients. You do not need to decode it yourself — just pass it as-is.

Refreshing tokens

When a 401 Unauthorized response indicates the access token has expired, call POST /api/v1/auth/refresh-token to obtain a new access token and a new refresh token. The old refresh token is consumed and a fresh one is returned — this is called token rotation.

curl -X POST https://your-api/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "abc123...",
    "useCookies": false
  }'

Request body

{
  "refreshToken": "abc123...",
  "useCookies": false
}

Response — 200 OK

{
  "accessToken": "eyJ...",
  "refreshToken": "xyz789..."
}

Implement automatic token refresh in your HTTP client: intercept 401 responses, call POST /api/v1/auth/refresh-token, update your stored tokens, and retry the original request. This gives users a seamless experience without being interrupted by login prompts every 15 minutes.

Cookie transport

If you originally logged in with useCookies: true, you can refresh tokens without supplying a refreshToken field in the request body. Alphabet reads the alphabet_refresh_token cookie automatically and writes the new cookies to the response.

curl -X POST https://your-api/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  --cookie "alphabet_refresh_token=abc123..." \
  -d '{}'

Cookie transport details

When cookie transport is active, Alphabet writes two cookies to every auth response:

Cookie name	Contents	Attributes
alphabet_access_token	Short-lived JWT	HttpOnly, Secure, SameSite=Lax
alphabet_refresh_token	Long-lived refresh token	HttpOnly, Secure, SameSite=Lax

The HttpOnly flag prevents JavaScript from reading the cookies, reducing XSS exposure. The Secure flag ensures they are only sent over HTTPS. SameSite=Lax provides baseline CSRF protection for cross-site navigations while allowing normal same-site requests.

Session termination

Self-service logout

An authenticated user can revoke their own session by calling POST /api/v1/auth/logout. This revokes the refresh token and clears both auth cookies.

curl -X POST https://your-api/api/v1/auth/logout \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "abc123..." }'

A 200 OK response confirms the session has been revoked. The access token remains technically valid until it expires (up to 15 minutes), so treat logout as best-effort for in-flight requests.

Admin-forced logout

An administrator can terminate all active sessions for any user with POST /api/v1/admin/users/{userId}/force-logout. This revokes all refresh tokens and rotates the user’s security stamp, causing all currently issued access tokens to fail authorization checks.

curl -X POST https://your-api/api/v1/admin/users/3f45ef0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/force-logout \
  -H "Authorization: Bearer <adminAccessToken>"

A 200 OK response means all sessions for that user are now invalid.

Force logout immediately invalidates all sessions. Use it for security incidents, account suspension, or at a user’s explicit request when they cannot log out themselves.

Error handling

Status	Trigger	Recommended action
401 Unauthorized	Access token is expired or invalid	Call POST /api/v1/auth/refresh-token and retry
400 Bad Request from /refresh-token	Refresh token is expired or has been revoked	Discard stored tokens and redirect the user to log in again

A 400 from /refresh-token means the refresh token is no longer usable — either it expired after 7 days, was consumed by a previous rotation, or was explicitly revoked by a logout or force-logout call. Your client must prompt the user to authenticate again.

{
  "title": "Refresh token failed",
  "detail": "The refresh token is invalid or has expired."
}