Use Refresh Token Rotation

To use refresh token rotation, you will use the Auth0 Single Page App SDK. The Auth0 SPA SDK handles token storage, session management, and other details for you.

Prerequisite

Configure refresh token rotation to enable offline access and request the offline access scope in the client SDK.

Enable useRefreshTokens

In compliance with the OAuth2 specifications, when a browser requests a refresh token from the /token endpoint, Auth0 will only return a refresh token if Refresh Token Rotation is enabled for that client.

Use the option useRefreshTokens on createAuth0Client which defaults to false. With this option set to false, when getTokenSilently() is invoked and a new Access Token is required, the SDK attempts to acquire a new Access Token using a hidden iframe and prompt=none.

If you set to this option to true, the offline_access scope is automatically requested when using loginWithRedirect(), loginWithPopup() and getTokenSilently(). When getTokenSilently() is invoked and the Access Token has expired, the SDK attempts to renew the ID and Access Tokens by calling the /token endpoint using the refresh_token grant type along with the Refresh Token from the cache.

Silent re-authentication is achieved by sending a prompt=none parameter upon the authentication request and using a hidden iframe, provided that there is an active user session on the authorization server. The SDK uses the iframe method if you have set useRefreshTokens to true but no Refresh Token is available in the cache. This helps users to silently migrate to using Refresh Tokens without making them log in again.

If the exchange fails because useRefreshTokens is true but there isn't a Refresh Token in the cache, then it falls back to the iframe method (which could also fail if third-party cookies are blocked).

Token storage

With SPAs, ID and Access Tokens are obtained from the authorization server and typically cached in memory. Token renewal (due to refreshing the browser, memory cache eviction budgets, or expiration) is handled by the SDK.

Example

The following example shows how to configure the SDK to use both local storage and refresh tokens:

const auth0 = await createAuth0Client({
    domain: '<your Auth0 domain>',
    client_id: '<your Auth0 client ID>',
    cacheLocation: 'localstorage',
    useRefreshTokens: true
    });
    
    // Logging-in will automatically request the offline_access scope
    // and store the resulting refresh token
    auth0.loginWithRedirect();
    
    // Silently refreshing the access token will use the /token endpoint
    // with ‘refresh_token’ grant and the refresh token from the cache
    await auth0.getTokenSilently();

Learn more