feat: add support for Online Access (Online Refresh Tokens)

Adds revokeRefreshToken() to the useAuth0 hook, wrapping the underlying
Auth0Client method and keeping isAuthenticated/user in sync after the call.
This is the one gap in Online Access support — refreshTokenMode, useDpop,
and useMrrt already pass through Auth0Provider's existing Auth0ClientOptions
config surface.

Also exports RefreshTokenMode, InvalidConfigurationError, MissingScopesError,
and RevokeRefreshTokenOptions from the package root, and documents the
feature in EXAMPLES.md.

Author: NandanPrabhu

EXAMPLES.md

@@ -11,6 +11,7 @@
 - [Protecting a route with a claims check](#protecting-a-route-with-a-claims-check)
 - [Device-bound tokens with DPoP](#device-bound-tokens-with-dpop)
 - [Using Multi Resource Refresh Tokens](#using-multi-resource-refresh-tokens)
+- [Online Access (Online Refresh Tokens)](#online-access-online-refresh-tokens)
 - [Connect Accounts for using Token Vault](#connect-accounts-for-using-token-vault)
 - [Access SDK Configuration](#access-sdk-configuration)
 - [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa)
@@ -783,6 +784,99 @@ MRRT is disabled by default. To enable it, set the `useMrrt` option to `true` wh
 > In order MRRT to work, it needs a previous configuration setting the refresh token policies.
 > Visit [configure and implement MRRT.](https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token/configure-and-implement-multi-resource-refresh-token)
 
+## Online Access (Online Refresh Tokens)
+
+**Online Refresh Tokens (ORTs)** are a refresh token type bound to the lifetime of the user's Auth0 session, unlike the rotating offline refresh tokens described above. An ORT is:
+
+- **Session-bound** — valid only while the underlying Auth0 session is active. When the session ends (logout, idle/absolute session expiry, or an admin revoking the session), the ORT stops working.
+- **Non-rotating** — refreshing an access token with an ORT does **not** issue a new refresh token; the same ORT is reused for the life of the session.
+
+Read more about [Online Refresh Tokens](https://auth0.com/docs/secure/tokens/refresh-tokens/online-refresh-tokens/online-refresh-tokens) to decide whether this fits your application.
+
+> [!IMPORTANT]
+> Online access requires DPoP. Sender-constraining the token via [DPoP](#device-bound-tokens-with-dpop) is mandatory because the ORT is non-rotating — binding it to the browser's key pair is what mitigates token replay if it is exfiltrated. You must set `useDpop={true}` explicitly; the SDK does not enable it for you.
+>
+> This also requires the `online_refresh_tokens` flag to be enabled for your Auth0 tenant, and `allow_online_access` to be enabled on the resource server you log in with (on by default).
+
+### Enabling Online Access
+
+Set `refreshTokenMode` to `RefreshTokenMode.Online` together with `useRefreshTokens={true}` and `useDpop={true}`:
+
+```jsx
+import { Auth0Provider, RefreshTokenMode } from '@auth0/auth0-react';
+
+<Auth0Provider
+  domain="YOUR_AUTH0_DOMAIN"
+  clientId="YOUR_AUTH0_CLIENT_ID"
+  useRefreshTokens={true} // required — online access is a refresh-token grant
+  refreshTokenMode={RefreshTokenMode.Online} // 👈
+  useDpop={true} // required — DPoP is mandatory for online access
+  authorizationParams={{ redirect_uri: window.location.origin }}
+>
+```
+
+`refreshTokenMode` defaults to `RefreshTokenMode.Offline` (the rotating refresh tokens described above). Enabling online mode causes the underlying SDK to:
+
+- Send the `online_access` scope to the authorization server (instead of `offline_access`) — you do **not** need to add it to `authorizationParams.scope` yourself.
+- Route token renewal through the `refresh_token` grant against `/oauth/token` rather than a hidden iframe.
+- Store the non-rotating ORT in the existing cache and reuse it on every refresh, never replacing it.
+
+### Configuration validation
+
+If `refreshTokenMode={RefreshTokenMode.Online}` is set without `useRefreshTokens={true}` and `useDpop={true}`, the underlying `Auth0Client` constructor throws an `InvalidConfigurationError`. Because `Auth0Provider` constructs the client during render, wrap it in an error boundary or validate your configuration up front:
+
+```jsx
+import { InvalidConfigurationError } from '@auth0/auth0-react';
+
+try {
+  // Constructing without useDpop={true} throws InvalidConfigurationError
+} catch (e) {
+  if (e instanceof InvalidConfigurationError) {
+    console.error(e.error_description); // includes the suggested fix
+  }
+}
+```
+
+### Revoking the Online Refresh Token
+
+Use `revokeRefreshToken()` from the `useAuth0` hook to explicitly revoke the refresh token via the `/oauth/revoke` endpoint:
+
+```jsx
+const { revokeRefreshToken } = useAuth0();
+
+await revokeRefreshToken();
+// Revoke for a specific audience:
+await revokeRefreshToken({ audience: 'https://api.example.com' });
+```
+
+> [!WARNING]
+> In online mode, `revokeRefreshToken()` behaves differently from offline mode:
+> - The ORT **is** revoked at the authorization server, and because it is session-bound, the Auth0 **session is terminated server-side** as part of revocation.
+> - The entire local cache is cleared immediately — `isAuthenticated` becomes `false` and `user` becomes `undefined` right away, without waiting for the access token to expire.
+>
+> In **offline mode**, only the refresh token is invalidated — the cached access token and user profile remain valid until the access token expires.
+>
+> After calling `revokeRefreshToken()` in online mode, redirect the user to login. For a redirect-based sign-out in either mode, use `logout()` instead.
+
+### Using Online Access with MRRT
+
+Online access is compatible with [MRRT](#using-multi-resource-refresh-tokens): a single ORT can be exchanged for access tokens across the audiences allowed by your refresh-token policies. The ORT remains non-rotating throughout.
+
+```jsx
+<Auth0Provider
+  domain="YOUR_AUTH0_DOMAIN"
+  clientId="YOUR_AUTH0_CLIENT_ID"
+  useRefreshTokens={true}
+  refreshTokenMode={RefreshTokenMode.Online}
+  useDpop={true}
+  useMrrt={true} // 👈
+  authorizationParams={{
+    redirect_uri: window.location.origin,
+    audience: 'https://api.example.com'
+  }}
+>
+```
+
 ## Connect Accounts for using Token Vault
 
 The Connect Accounts feature uses the Auth0 My Account API to allow users to link multiple third party accounts to a single Auth0 user profile.

__mocks__/@auth0/auth0-spa-js.tsx

@@ -16,6 +16,7 @@ const loginWithPopup = jest.fn();
 const loginWithRedirect = jest.fn();
 const connectAccountWithRedirect = jest.fn();
 const logout = jest.fn();
+const revokeRefreshToken = jest.fn();
 const getDpopNonce = jest.fn();
 const setDpopNonce = jest.fn();
 const generateDpopProof = jest.fn();
@@ -56,6 +57,7 @@ export const Auth0Client = jest.fn(() => {
     loginWithRedirect,
     connectAccountWithRedirect,
     logout,
+    revokeRefreshToken,
     getDpopNonce,
     setDpopNonce,
     generateDpopProof,
@@ -85,6 +87,9 @@ export const Auth0Client = jest.fn(() => {
 });
 
 export const ResponseType = actual.ResponseType;
+export const RefreshTokenMode = actual.RefreshTokenMode;
+export const InvalidConfigurationError = actual.InvalidConfigurationError;
+export const MissingScopesError = actual.MissingScopesError;
 
 export const MfaError = actual.MfaError;
 export const MfaListAuthenticatorsError = actual.MfaListAuthenticatorsError;

__tests__/auth-provider.test.tsx

@@ -1,7 +1,8 @@
 import {
   Auth0Client, ConnectAccountRedirectResult,
   GetTokenSilentlyVerboseResponse,
-  ResponseType
+  ResponseType,
+  RefreshTokenMode
 } from '@auth0/auth0-spa-js';
 import '@testing-library/jest-dom';
 import { act, render, renderHook, screen, waitFor } from '@testing-library/react';
@@ -61,6 +62,33 @@ describe('Auth0Provider', () => {
     });
   });
 
+  it('should forward online-access options to Auth0Client', async () => {
+    const opts = {
+      clientId: 'foo',
+      domain: 'bar',
+      useRefreshTokens: true,
+      useDpop: true,
+      useMrrt: true,
+      refreshTokenMode: RefreshTokenMode.Online,
+    };
+    const wrapper = createWrapper(opts);
+    renderHook(() => useContext(Auth0Context), {
+      wrapper,
+    });
+    await waitFor(() => {
+      expect(Auth0Client).toHaveBeenCalledWith(
+        expect.objectContaining({
+          clientId: 'foo',
+          domain: 'bar',
+          useRefreshTokens: true,
+          useDpop: true,
+          useMrrt: true,
+          refreshTokenMode: 'online',
+        })
+      );
+    });
+  });
+
   it('should support redirectUri', async () => {
     const warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
     const opts = {
@@ -603,6 +631,107 @@ describe('Auth0Provider', () => {
     });
   });
 
+  it('should provide a revokeRefreshToken method', async () => {
+    const user = { name: '__test_user__' };
+    clientMock.getUser.mockResolvedValue(user);
+    const wrapper = createWrapper();
+    const { result } = renderHook(
+      () => useContext(Auth0Context),
+      { wrapper }
+    );
+    await waitFor(() => {
+      expect(result.current.revokeRefreshToken).toBeInstanceOf(Function);
+      expect(result.current.isAuthenticated).toBe(true);
+    });
+    await act(async () => {
+      await result.current.revokeRefreshToken();
+    });
+    expect(clientMock.revokeRefreshToken).toHaveBeenCalled();
+  });
+
+  it('should forward options to revokeRefreshToken', async () => {
+    const user = { name: '__test_user__' };
+    clientMock.getUser.mockResolvedValue(user);
+    const wrapper = createWrapper();
+    const { result } = renderHook(
+      () => useContext(Auth0Context),
+      { wrapper }
+    );
+    await waitFor(() => {
+      expect(result.current.isAuthenticated).toBe(true);
+    });
+    await act(async () => {
+      await result.current.revokeRefreshToken({ audience: 'https://api.example.com' });
+    });
+    expect(clientMock.revokeRefreshToken).toHaveBeenCalledWith({
+      audience: 'https://api.example.com',
+    });
+  });
+
+  it('should reflect cleared session state after revokeRefreshToken in online mode', async () => {
+    // In online mode, revokeRefreshToken() clears the entire local session server-side.
+    // getUser() reflects this by resolving to undefined afterward.
+    const user = { name: '__test_user__' };
+    clientMock.getUser.mockResolvedValueOnce(user);
+    const wrapper = createWrapper();
+    const { result } = renderHook(
+      () => useContext(Auth0Context),
+      { wrapper }
+    );
+    await waitFor(() => {
+      expect(result.current.isAuthenticated).toBe(true);
+    });
+    clientMock.getUser.mockResolvedValueOnce(undefined);
+    await act(async () => {
+      await result.current.revokeRefreshToken();
+    });
+    await waitFor(() => {
+      expect(result.current.isAuthenticated).toBe(false);
+      expect(result.current.user).toBeUndefined();
+    });
+  });
+
+  it('should not change session state after revokeRefreshToken in offline mode', async () => {
+    // In offline mode, revokeRefreshToken() only invalidates the refresh token;
+    // the cached user/access token remain valid until they expire.
+    const user = { name: '__test_user__' };
+    clientMock.getUser.mockResolvedValue(user);
+    const wrapper = createWrapper();
+    const { result } = renderHook(
+      () => useContext(Auth0Context),
+      { wrapper }
+    );
+    await waitFor(() => {
+      expect(result.current.isAuthenticated).toBe(true);
+    });
+    await act(async () => {
+      await result.current.revokeRefreshToken();
+    });
+    expect(result.current.isAuthenticated).toBe(true);
+    expect(result.current.user).toBe(user);
+  });
+
+  it('should rethrow errors from revokeRefreshToken', async () => {
+    const user = { name: '__test_user__' };
+    clientMock.getUser.mockResolvedValue(user);
+    clientMock.revokeRefreshToken.mockRejectedValueOnce(
+      new Error('The token has been revoked')
+    );
+    const wrapper = createWrapper();
+    const { result } = renderHook(
+      () => useContext(Auth0Context),
+      { wrapper }
+    );
+    await waitFor(() => {
+      expect(result.current.isAuthenticated).toBe(true);
+    });
+    await expect(
+      act(async () => {
+        await result.current.revokeRefreshToken();
+      })
+    ).rejects.toThrow('The token has been revoked');
+  });
+
   it('should provide a getAccessTokenSilently method', async () => {
     clientMock.getTokenSilently.mockResolvedValue('token');
     const wrapper = createWrapper();

src/auth0-context.tsx

@@ -16,7 +16,8 @@ import {
   TokenEndpointResponse,
   type MfaApiClient,
   type PasskeyApiClient,
-  type MyAccountApiClient
+  type MyAccountApiClient,
+  type RevokeRefreshTokenOptions
 } from '@auth0/auth0-spa-js';
 import { createContext } from 'react';
 import { AuthState, initialAuthState } from './auth-state';
@@ -273,6 +274,37 @@ export interface Auth0ContextInterface<TUser extends User = User>
    */
   logout: (options?: LogoutOptions) => Promise<void>;
 
+  /**
+   * ```js
+   * await revokeRefreshToken();
+   * ```
+   *
+   * Revokes the refresh token via the `/oauth/revoke` endpoint. This invalidates the
+   * refresh token so it can no longer be used to obtain new access tokens.
+   *
+   * If `useRefreshTokens` is disabled, this method does nothing.
+   *
+   * **Online mode** (`refreshTokenMode: RefreshTokenMode.Online`): revoking the Online
+   * Refresh Token also terminates the Auth0 session server-side and clears the entire
+   * local cache. `isAuthenticated` and `user` update immediately to reflect the
+   * terminated session — no redirect required. Use `logout()` instead if you want a
+   * redirect-based sign-out.
+   *
+   * **Offline mode**: only the refresh token is invalidated; the cached access token
+   * and user profile remain valid until the access token expires. `isAuthenticated`
+   * and `user` are unaffected until then.
+   *
+   * @param options - Optional parameters to identify which refresh token to revoke.
+   *   Defaults to the audience configured in `authorizationParams`.
+   *
+   * @example
+   * ```js
+   * const { revokeRefreshToken } = useAuth0();
+   * await revokeRefreshToken();
+   * ```
+   */
+  revokeRefreshToken: (options?: RevokeRefreshTokenOptions) => Promise<void>;
+
   /**
    * After the browser redirects back to the callback page,
    * call `handleRedirectCallback` to handle success and error
@@ -470,6 +502,7 @@ export const initialContext = {
   loginWithPopup: stub,
   connectAccountWithRedirect: stub,
   logout: stub,
+  revokeRefreshToken: stub,
   handleRedirectCallback: stub,
   getDpopNonce: stub,
   setDpopNonce: stub,

src/auth0-provider.tsx

@@ -22,7 +22,8 @@ import {
   TokenEndpointResponse,
   type PasskeyApiClient,
   type PasskeySignupOptions,
-  type PasskeyLoginOptions
+  type PasskeyLoginOptions,
+  type RevokeRefreshTokenOptions
 } from '@auth0/auth0-spa-js';
 import Auth0Context, {
   Auth0ContextInterface,
@@ -259,6 +260,21 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     [client]
   );
 
+  const revokeRefreshToken = useCallback(
+    async (opts?: RevokeRefreshTokenOptions): Promise<void> => {
+      await client.revokeRefreshToken(opts);
+      // Online mode clears the entire local session as part of revocation; offline
+      // mode leaves the cached access token/user untouched. Re-reading the user from
+      // the client after either case keeps isAuthenticated/user consistent with
+      // whatever the SDK actually did, without assuming which mode is active.
+      dispatch({
+        type: 'GET_ACCESS_TOKEN_COMPLETE',
+        user: await client.getUser(),
+      });
+    },
+    [client]
+  );
+
   const getAccessTokenSilently = useCallback(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async (opts?: GetTokenSilentlyOptions): Promise<any> => {
@@ -449,6 +465,7 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
       loginWithPopup,
       connectAccountWithRedirect,
       logout,
+      revokeRefreshToken,
       handleRedirectCallback,
       getDpopNonce,
       setDpopNonce,
@@ -471,6 +488,7 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     loginWithPopup,
     connectAccountWithRedirect,
     logout,
+    revokeRefreshToken,
     handleRedirectCallback,
     getDpopNonce,
     setDpopNonce,