Token Lifecycle

This guide explains how tokens are managed throughout their lifecycle, including initialization, validation, renewal, and cleanup.

Each token type has a different default expiration:

When initializeSession() is called:

┌─────────────────────────────────────────────────────────────┐
│                    initializeSession()                       │
├─────────────────────────────────────────────────────────────┤
│  1. Check if refresh token exists and is valid              │
│     - If invalid, clear all tokens                          │
│     - If authOnly behavior and invalid, throw error         │
│                                                             │
│  2. If auth enabled and refresh token valid:                │
│     - Check if auth token is valid                          │
│     - If invalid, call refreshAuthToken()                   │
│                                                             │
│  3. If session token invalid:                               │
│     - Call startSession() to get new session token          │
│                                                             │
│  4. If withClientSession behavior:                          │
│     - Generate client session ID                            │
│     - Call updateSession() to save it server-side           │
│     - Start client session ID renewal timer                 │
│                                                             │
│  5. Mark session as initialized if hasTokens() returns true │
└─────────────────────────────────────────────────────────────┘

Tokens are validated using JWT decoding. The isTokenValid() function checks:

• Token can be decoded as a valid JWT
• Token has not expired (based on exp claim)

// Example validation flow
if (!isTokenValid(sessionToken)) {
  // Token is expired or malformed
  await tokenManager.renewTokens();
}

When configured with SessionBehavior.withAuth or SessionBehavior.authOnly, the TokenManager can automatically refresh auth tokens:

• The startAuthTokenManager() method creates an interval timer
• Default interval: 10 minutes (configurable via AUTH_FETCH_INTERVAL env var)
• On each interval, checks if tokens exist and refreshes the auth token

When configured with SessionBehavior.withClientSession:

• The startClientSessionIdManager() method creates an interval timer
• Interval: 45 minutes
• On each interval, generates a new client session ID and updates the server

Call renewTokens() to manually refresh tokens:

await tokenManager.renewTokens();

This method:

1. Validates the refresh token (clears all if invalid)
2. Refreshes the auth token if refresh token is valid
3. Fetches a new session token if current one is invalid
4. Updates the client session ID if that behavior is enabled

Pass bypassClient = true to skip client session ID update:

await tokenManager.renewTokens(true);

Call endSession() to terminate the session:

tokenManager.endSession();

This method:

1. Clears the auth token renewal timer
2. Clears the client session ID renewal timer
3. Removes all tokens from storage
4. Resets the initialized flag to false

The isReady() method returns true only when all required tokens are valid:

┌─────────────────────────────────────────────────────────────┐
│                        isReady()                            │
├─────────────────────────────────────────────────────────────┤
│  Returns FALSE if:                                          │
│  - Session is not initialized                               │
│  - Required tokens don't exist (hasTokens() returns false)  │
│  - Auth required but refresh/auth token invalid             │
│  - Session token is invalid                                 │
│  - Client session ID enabled but invalid                    │
│                                                             │
│  Returns TRUE if:                                           │
│  - All required tokens exist and are valid                  │
└─────────────────────────────────────────────────────────────┘

The TokenManager generates unique storage keys for each token based on the manager ID:

The exact key format is determined by the createClientStorageKey() utility and can be customized via environment variables.

if (!tokenManager.isReady()) {
  await tokenManager.renewTokens();
}

const { sessionToken, authToken } = tokenManager.getTokens();
// Make your GraphQL request

try {
  const result = await makeGraphQLRequest();
} catch (error) {
  if (isAuthenticationError(error)) {
    await tokenManager.renewTokens();
    // Retry the request
  }
}

async function logout() {
  // Call your logout mutation
  await logoutMutation();

  // End the token manager session
  tokenManager.endSession();

  // Redirect to home or login page
  router.push('/');
}

• Session Behaviors - Configure which tokens are required
• Storage Implementations - How tokens are persisted
• Client Session ID Usage - Device tracking and session handoff