Skip to content

Commit c9a99fc

Browse files
authored
docs: note that Online Refresh Tokens don't support Ephemeral Sessions yet (#1677)
## Summary Adds a `[!WARNING]` note to both `README.md` and `EXAMPLES.md` under the "Online Access" sections stating that Online Refresh Tokens (ORTs) do not currently support resource servers with **Ephemeral Sessions** enabled. ## Changes - `README.md` — added a `[!WARNING]` under `### Online Access` - `EXAMPLES.md` — added the same `[!WARNING]` under `## Online Access (Online Refresh Tokens)`, right after the existing Early Access note Both note the workaround: disable "Allow for Ephemeral Sessions" on any resource server used with `refreshTokenMode: RefreshTokenMode.Online` until backend support lands. Docs-only change, no code or behavior changes. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a WARNING that Online Refresh Tokens are incompatible with resource servers that have **Ephemeral Sessions** enabled. * Documented the expected refresh behavior (`invalid_grant` / “Unknown or invalid refresh token”). * Added guidance to disable **Allow for Ephemeral Sessions** when using `refreshTokenMode: RefreshTokenMode.Online`. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 9615071 commit c9a99fc

2 files changed

Lines changed: 6 additions & 0 deletions

File tree

EXAMPLES.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,9 @@ await auth0.revokeRefreshToken();
225225
> [!NOTE]
226226
> Online Access (Online Refresh Tokens) support via SDKs is currently in Early Access. To request access to this feature, contact your Auth0 representative.
227227
228+
> [!WARNING]
229+
> Online Refresh Tokens do not currently support resource servers with **Ephemeral Sessions** enabled. If a resource server has both `allow_online_access` and "Allow for Ephemeral Sessions" enabled, the authorization server issues an Online Refresh Token at login that is then rejected with `invalid_grant` (`"Unknown or invalid refresh token"`) on the very next refresh — this is a known backend limitation, not a client-side defect. Until Ephemeral Sessions support is added for Online Refresh Tokens, disable "Allow for Ephemeral Sessions" on any resource server used with `refreshTokenMode: RefreshTokenMode.Online`.
230+
228231
**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:
229232

230233
- **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.

README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,9 @@ window.addEventListener('load', async () => {
119119
> [!NOTE]
120120
> Online Access (Online Refresh Tokens) support via SDKs is currently in Early Access. To request access to this feature, contact your Auth0 representative.
121121
122+
> [!WARNING]
123+
> Online Refresh Tokens do not currently support resource servers with **Ephemeral Sessions** enabled. Enabling both `allow_online_access` and "Allow for Ephemeral Sessions" on the same resource server results in the authorization server issuing an Online Refresh Token that is then rejected (`invalid_grant`) on the very next refresh. Until Ephemeral Sessions support is added for Online Refresh Tokens, disable "Allow for Ephemeral Sessions" on any resource server used with `refreshTokenMode: RefreshTokenMode.Online`.
124+
122125
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.
123126

124127
```js

0 commit comments

Comments
 (0)