feat: add support for online access (Online Refresh Tokens) (#1624)

## Summary
Adds support for **Online Refresh Tokens (ORTs)** — non-rotating refresh
tokens bound to the Auth0 session lifetime (unlike the existing rotating
offline refresh tokens).
Opt in via the new `refreshTokenMode` option:
                                                    
```ts
  const auth0 = await createAuth0Client({
domain,
clientId,
    useRefreshTokens: true,                         
    refreshTokenMode: RefreshTokenMode.Online, // defaults to Offline
useDpop: true // required for online access
  });
  ```

`refreshTokenMode` defaults to `RefreshTokenMode.Offline`, so **existing
apps are unaffected**.

  ## What it does

- Injects `online_access` (instead of `offline_access`) and routes
renewal through the refresh-token grant.
  - Reuses the same ORT on every refresh (non-rotating).
- Requires `useDpop: true`, enforced at compile time (typed overloads)
and runtime (`InvalidConfigurationError`).
Requires `online_refresh_tokens` (tenant) and `allow_online_access`
(resource server, on by default). See
  [EXAMPLES.md](./EXAMPLES.md#online-access-online-refresh-tokens).

---------

Co-authored-by: Nandan Prabhu <nandan.prabhup@okta.com>

Author: subhankarmaiti

EXAMPLES.md

@@ -3,6 +3,7 @@
 - [Logging Out](#logging-out)
 - [Calling an API](#calling-an-api)
 - [Refresh Tokens](#refresh-tokens)
+- [Online Access (Online Refresh Tokens)](#online-access-online-refresh-tokens)
 - [Data Caching Options](#creating-a-custom-cache)
 - [Organizations](#organizations)
 - [Native to Web SSO](#native-to-web-sso)
@@ -153,6 +154,9 @@ The `revokeRefreshToken()` method explicitly revokes a refresh token via the `/o
 
 This method only has an effect when `useRefreshTokens` is `true`. If refresh tokens are disabled it returns immediately without doing anything.
 
+> [!NOTE]
+> In [online access](#online-access-online-refresh-tokens) mode (`refreshTokenMode: RefreshTokenMode.Online`), `revokeRefreshToken()` only clears the cached refresh token locally — it does **not** revoke the Online Refresh Token at the authorization server. Online Refresh Tokens are non-rotating and session-bound, and the server does not support token-only revocation for them. To end an online session, call `logout()` instead, which terminates the session and thereby invalidates the ORT.
+
 ```js
 // Revoke the refresh token for the default audience
 await auth0.revokeRefreshToken();
@@ -205,6 +209,141 @@ When using [Multi-Resource Refresh Tokens (MRRT)](#using-multi-resource-refresh-
 await auth0.revokeRefreshToken();
 ```
 
+## Online Access (Online Refresh Tokens)
+
+**Online Refresh Tokens (ORTs)** are a refresh token type bound to the lifetime of the user's Auth0 session. See the [Auth0 documentation on Online Refresh Tokens](https://auth0.com/docs/secure/tokens/refresh-tokens/online-refresh-tokens/online-refresh-tokens) for the full conceptual overview. Unlike the rotating [offline refresh tokens](#refresh-tokens) described above, an ORT is:
+
+- **Session-bound** — it is 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.
+
+This makes ORTs a good fit for SPAs that want a refresh-token renewal path whose lifetime tracks the SSO session rather than living independently of it.
+
+> [!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.
+
+### Enabling Online Access
+
+Set `refreshTokenMode` to `RefreshTokenMode.Online` together with `useRefreshTokens: true` and `useDpop: true`:
+
+```js
+import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
+const auth0 = await createAuth0Client({
+  domain: '<AUTH0_DOMAIN>',
+  clientId: '<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: '<MY_CALLBACK_URL>'
+  }
+});
+```
+
+`refreshTokenMode` is a sub-option of `useRefreshTokens`. It defaults to `RefreshTokenMode.Offline` (the rotating [offline refresh tokens](#refresh-tokens) described above); setting it to `RefreshTokenMode.Online` opts into Online Refresh Tokens. Always reference the exported `RefreshTokenMode` enum rather than hard-coding the mode.
+
+Enabling this option causes the 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 — the SDK injects it.
+- Route token renewal through the `refresh_token` grant against `/oauth/token` (the same path used by offline refresh tokens), rather than a hidden iframe.
+- Store the non-rotating ORT in the existing cache and reuse it on every refresh, never replacing it.
+
+> [!NOTE]
+> Online access is **opt-in**. When `refreshTokenMode` is unset or `RefreshTokenMode.Offline`, the SDK behaves exactly as before.
+
+> [!NOTE]
+> This feature requires the `online_refresh_tokens` flag to be enabled for your tenant and `allow_online_access` to be enabled on the resource server (on by default).
+
+### `RefreshTokenMode.Offline` vs. `RefreshTokenMode.Online`
+
+`refreshTokenMode` selects which refresh-token type the refresh-token grant uses. It is a sub-option of `useRefreshTokens` (which must be `true` for either mode) and defaults to `RefreshTokenMode.Offline`:
+
+| | `RefreshTokenMode.Offline` (default) | `RefreshTokenMode.Online` |
+| --- | --- | --- |
+| Requires | `useRefreshTokens: true` | `useRefreshTokens: true` + `useDpop: true` |
+| Scope injected | `offline_access` | `online_access` |
+| Token lifetime | Independent of the session (survives logout until revoked/expired) | Bound to the Auth0 session |
+| Rotation | Rotating (a new RT is issued on each refresh) | Non-rotating (same RT reused) |
+| DPoP | Optional | **Required** (`useDpop: true`) |
+
+The two modes inject mutually exclusive scopes (`offline_access` vs. `online_access`), so the SDK emits only one — it never sends both. You select between them with `refreshTokenMode`, not by combining flags.
+
+### Configuration validation
+
+The SDK enforces the DPoP requirement at two layers:
+
+1. **Compile-time (TypeScript).** When you call `createAuth0Client` with `refreshTokenMode: RefreshTokenMode.Online`, the compiler requires both `useRefreshTokens: true` and `useDpop: true`:
+
+   ```ts
+   import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
+   // ❌ compile error: `useRefreshTokens: true` and `useDpop: true` are required for online mode
+   createAuth0Client({ domain, clientId, refreshTokenMode: RefreshTokenMode.Online });
+
+   // ❌ compile error: `useDpop: true` is still required
+   createAuth0Client({ domain, clientId, refreshTokenMode: RefreshTokenMode.Online, useRefreshTokens: true });
+
+   // ✅ valid
+   createAuth0Client({ domain, clientId, refreshTokenMode: RefreshTokenMode.Online, useRefreshTokens: true, useDpop: true });
+   ```
+
+   > [!NOTE]
+   > The compile-time check narrows on the online mode value. A dynamically-typed value (e.g. a `refreshTokenMode` read from config at runtime), an `as any` cast, or plain JavaScript all bypass it — which is why the runtime check below exists too.
+
+2. **Runtime (all consumers, including plain JS).** The `Auth0Client` constructor throws an `InvalidConfigurationError` when online mode is requested but `useRefreshTokens` or `useDpop` is not `true`. The error's `suggestion` tells you exactly which option to set:
+
+   ```js
+   import { createAuth0Client, RefreshTokenMode, InvalidConfigurationError } from '@auth0/auth0-spa-js';
+
+   try {
+     const auth0 = await createAuth0Client({
+       domain: '<AUTH0_DOMAIN>',
+       clientId: '<AUTH0_CLIENT_ID>',
+       refreshTokenMode: RefreshTokenMode.Online,
+       useRefreshTokens: true // missing useDpop: true
+     });
+   } catch (e) {
+     if (e instanceof InvalidConfigurationError) {
+       console.error(e.error_description); // includes the suggested fix
+       console.error(e.suggestion); // 'Set `useDpop: true` (DPoP is mandatory for online access).'
+     }
+   }
+   ```
+
+### Logging out
+
+Because an ORT is bound to the Auth0 session, the way to invalidate it is to end the session with `logout()`, which clears the local cache and redirects to `/v2/logout`:
+
+```js
+await auth0.logout({ logoutParams: { returnTo: window.location.origin } });
+```
+
+After logout, the ORT is no longer valid; a subsequent `getTokenSilently()` falls through to the [iframe fallback](#refresh-token-fallback) (if `useRefreshTokensFallback` is enabled) and ultimately to an interactive login.
+
+> [!NOTE]
+> In online mode, [`revokeRefreshToken()`](#revoking-refresh-tokens) only clears the cached token locally — it does **not** revoke the ORT at the authorization server. The server has no token-only revocation for non-rotating ORTs, so `logout()` is the only way to invalidate an ORT.
+
+### Using with Multi-Resource Refresh Tokens (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 — the same token is reused for every cross-audience exchange.
+
+```js
+import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
+const auth0 = await createAuth0Client({
+  domain: '<AUTH0_DOMAIN>',
+  clientId: '<AUTH0_CLIENT_ID>',
+  useRefreshTokens: true,
+  refreshTokenMode: RefreshTokenMode.Online,
+  useDpop: true,
+  useMrrt: true,
+  authorizationParams: {
+    redirect_uri: '<MY_CALLBACK_URL>',
+    audience: 'https://api.example.com'
+  }
+});
+```
+
 ## Data caching options
 
 The SDK can be configured to cache ID tokens and access tokens either in memory or in local storage. The default is in memory. This setting can be controlled using the `cacheLocation` option when creating the Auth0 client.

README.md

@@ -114,9 +114,30 @@ window.addEventListener('load', async () => {
 });
 ```
 
+### Online Access
+
+Set `refreshTokenMode` to `RefreshTokenMode.Online` (together with the required `useRefreshTokens: true` and `useDpop: true`) to use **Online Refresh Tokens** — non-rotating refresh tokens bound to the Auth0 session lifetime. The SDK injects the `online_access` scope and routes renewal through the refresh-token grant.
+
+```js
+import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
+const auth0 = await createAuth0Client({
+  domain: '<AUTH0_DOMAIN>',
+  clientId: '<AUTH0_CLIENT_ID>',
+  useRefreshTokens: true,
+  refreshTokenMode: RefreshTokenMode.Online,
+  useDpop: true,
+  authorizationParams: {
+    redirect_uri: '<MY_CALLBACK_URL>'
+  }
+});
+```
+
+`refreshTokenMode` is a sub-option of `useRefreshTokens`: it defaults to `RefreshTokenMode.Offline` (the rotating refresh tokens described above) and must be set to `RefreshTokenMode.Online` for Online Refresh Tokens. Online mode requires both `useRefreshTokens: true` and `useDpop: true`. See [Online Access](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md#online-access-online-refresh-tokens) in EXAMPLES.md for the full guide.
+
 ### More Examples
 
-For comprehensive examples covering various scenarios including logging out, calling APIs, refresh tokens, organizations, passkeys, MFA, DPoP, and more, see the [EXAMPLES.md](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md) document.
+For comprehensive examples covering various scenarios including logging out, calling APIs, refresh tokens, online access, organizations, passkeys, MFA, DPoP, and more, see the [EXAMPLES.md](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md) document.
 
 ## API Reference
 

__tests__/Auth0Client.utils.test.ts

@@ -0,0 +1,43 @@
+import { getMissingScopes } from '../src/Auth0Client.utils';
+
+/**
+ * `online_access` is stripped from the requested scopes only when `onlineAccess` is true:
+ * in online mode the server reuses the same (non-rotating) ORT for an MRRT cross-audience
+ * exchange and never echoes `online_access` back in the response scope, so comparing it
+ * would flag a spurious missing scope. Outside online mode the strip is not applied, so a
+ * genuinely missing `online_access` is still reported. `offline_access` is never excluded —
+ * the server echoes it back, so a genuinely missing `offline_access` should still be reported.
+ */
+describe('getMissingScopes', () => {
+  describe('in online mode', () => {
+    it('does not report online_access as missing', () => {
+      expect(
+        getMissingScopes('openid online_access fs:read', 'openid fs:read', true)
+      ).toBe('');
+    });
+
+    it('still reports genuinely missing resource scopes', () => {
+      expect(
+        getMissingScopes(
+          'openid online_access fs:read fs:write',
+          'openid fs:read',
+          true
+        )
+      ).toBe('fs:write');
+    });
+  });
+
+  describe('outside online mode', () => {
+    it('reports a genuinely missing online_access', () => {
+      expect(
+        getMissingScopes('openid online_access fs:read', 'openid fs:read')
+      ).toBe('online_access');
+    });
+
+    it('still reports a genuinely missing offline_access', () => {
+      expect(
+        getMissingScopes('openid offline_access fs:read', 'openid fs:read')
+      ).toBe('offline_access');
+    });
+  });
+});