Token scenarios

This page explains how the application behaves depending on the state of the access token and refresh token.

Quick reference

1. Access and Refresh are valid

Behavior:

• Allow the request.
• Use the access token normally.
• No refresh needed.

2. Access is invalid and Refresh is valid

Behavior:

• Attempt to refresh the access token using the refresh token.
• If refresh succeeds:
  • Store the new access token (and refresh token if rotated).
  • Retry the original request.
• If refresh fails:
  • Log out the user.

3. Access is valid and Refresh is invalid

Behavior:

• Allow the requests (access token still works).
• Do NOT attempt refresh until access token expires.
• When access token expires:
  • Refresh fails → log out the user.

4. Access and Refresh are invalid

Behavior:

• Reject the request.
• Immediately log out the user.
• Redirect to login.

5. Access doesn’t exist and Refresh does

Behavior:

• Attempt to generate a new access token using the refresh token.
• If successful:
  • Store new access token.
  • Proceed with the request.
• If it fails:
  • Log out the user.

6. Access exists and Refresh doesn’t

Behavior:

• Allow requests while access token is valid.
• When access token expires:
  • No fallback → log out the user.

7. Access and Refresh are manually deleted by user

Expected behavior:

• Treat as unauthenticated state.
• Redirect to login.
• Clear any local session state if needed.

Where this is implemented

• Refresh logic: src/lib/token/RefreshToken.ts
• Cross-tab session refresh: /api/auth/session-refresh (sets a short-lived recently_refreshed cookie so verifyAuth doesn’t loop on a token that is still near expiry right after a refresh)
• Logout: /api/logout — see Logout Implementation

See API Calls for the full list of auth-related routes.