Refreshing Access Tokens

Learn how to automatically refresh expired access tokens and handle token refresh failures in a backend server integration.

Overview

Access tokens have a limited lifetime and must be refreshed when they expire. With a backend server integration, your application can automatically refresh expired access tokens using the refresh token stored in the user's application session, allowing users to remain authenticated without having to log in again.

How Access Token Refresh Works

The following steps illustrate how a backend server refreshes an expired access token during an authenticated API request.

  1. Client Sends an API Request: The frontend sends a request to a protected API on your backend server. The browser automatically includes the application's session cookie with the request.

  2. Middleware Validates the Session: Before executing the requested API's business logic, authentication middleware retrieves the user's session data, including the access token, refresh token, and access token expiration time.

  3. Middleware Refreshes the Access Token: If the access token has expired or is approaching expiration, the middleware calls Wristband's Token Endpoint using the refresh_token grant type and includes the refresh token from the user's session.

  4. Wristband Issues a New Access Token: Wristband validates the refresh token and, if valid, returns a new access token and its expiration information. If refresh token rotation is enabled, then a new refresh token will be issued as well.

  5. Middleware Updates the Session: The middleware updates the user's session with the new access token and expiration time. If a new refresh token is returned, the session is also updated with that token.

  6. Protected API Executes: Once a valid access token is available and the session has been updated, the middleware allows the request to proceed to the protected API's business logic.

Refresh Token Flow

Figure 1: Backend authentication middleware refreshes the access token and updates the user's session before allowing the protected API request to proceed.

Handling Refresh Failures

A token refresh request may fail for several reasons:

  • Expired Refresh Token: The refresh token has exceeded its configured lifetime.
  • Revoked Refresh Token: The refresh token has been revoked and can no longer be used.
  • Invalid Refresh Token: The refresh token is malformed, has been tampered with, or is otherwise invalid.
  • Network or Server Errors: Connectivity issues, timeouts, or Wristband server errors prevent the refresh request from completing.
  • Client Authentication Errors: Invalid OAuth2 client credentials prevent the backend server from authenticating with Wristband.

Your application should handle these failures based on the underlying cause.

Server-Side Error Handling

When a token refresh request fails because the refresh token is invalid, expired, or revoked, the backend server should return a 401 Unauthorized response to the frontend.

For temporary failures, such as network errors or Wristband server errors, the backend server can retry the refresh request with exponential backoff. If the refresh continues to fail, it should return an appropriate error response, such as 503 Service Unavailable, rather than treating the user's session as invalid.

Client-Side Error Handling

When the frontend receives a 401 Unauthorized response indicating that the access token could not be refreshed, it should handle the authentication failure by clearing any locally stored authentication state and initiating the appropriate session cleanup.

There are two common approaches:

  1. Redirect to Login Without Terminating the Wristband Auth Session: Clear the application's session information and redirect the user to the application's Login Endpoint without calling Wristband's Logout Endpoint. If the user still has a valid Wristband authentication session, Wristband may automatically reauthenticate them without requiring them to log in again.

  2. Full Logout and Re-authentication: Clear the application's session information and redirect the user to Wristband's Logout Endpoint to terminate their Wristband authentication session. The user must then complete a new authentication flow to access the application.


Did this page help you?