Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0.com/llms.txt

Use this file to discover all available pages before exploring further.

Online Refresh Tokens (ORTs) are a type of refresh token designed specifically for browser-based applications, such as single-page applications (SPAs). ORTs can keep track of a user’s session in SPAs when browser privacy features like Intelligent Tracking Prevention (ITP) block access to third-party cookies, making traditional silent authentication unreliable. ORTs are bound to the user’s Auth0 session and can only be used while that session is active, ensuring that when a user logs out all applications using that session are logged out together.

​
How it works

When you request an ORT:
  1. Your application includes the online_access scope in the authorization request.
  2. Auth0 returns an ORT bound to the user’s current session.
  3. Each time you exchange the ORT for a new access token, Auth0 extends the session’s idle timeout.
  4. The token remains valid as long as the underlying Auth0 session is active.

​
Comparison of ORTs versus refresh tokens

FeatureORTsrefresh token
Scope requestedonline_accessoffline_access
Session bindingBound to Auth0 sessionIndependent of session
LifetimeDetermined by session lifetimeConfigured token lifetime
Token rotationDoes not rotateSupports rotation
Demonstration of Proof of Possession (DPoP) requirementRequired for public clients (SPA, Native)Optional (resource server config)
RevocationRevokes the entire sessionRevokes only the token
Management APINot visibleVisible via the Management API
Session idle timeoutExtended on each exchangeNo effect on session

​
Key behavioral differences

Session extension: When you exchange an ORT, Auth0 resets the session idle timeout, keeping the user session alive. Auth0 does not extend the session’s absolute lifetime. No rotation: Auth0 does not rotate ORTs. This is because ORTs are stateless and are bound to the session rather than stored individually. DPoP enforcement: For public clients (such as SPAs), Auth0 requires DPoP when using ORTs. Because ORTs operate at the same security level as a session cookie granting access to the user’s authenticated session, they must be protected with the same rigor. DPoP prevents token theft and replay attacks. Stateless: ORTs are bound to a session, so they cannot be seen or managed independently. You cannot see them in the Management API or revoke them individually.

​
Best practices

  1. Store tokens in memory: Avoid storing ORTs in localStorage or sessionStorage. Keep them in JavaScript memory for better security. Since ORTs are bound to the Auth0 session, the session cookie will re-establish context on the user’s next visit, allowing your app to request a fresh ORT.
  2. Handle session expiration gracefully: Implement proper error handling for cases when the session has expired. Redirect users to re-authenticate without losing their work.
  3. Use DPoP for public clients: ORTs require DPoP for public clients. Ensure your implementation generates and uses DPoP proofs correctly.
  4. Do not rely on token structure: Treat ORTs as opaque strings. Don’t parse or rely on any internal structure—this may change.
  5. Monitor session lifetime: Be aware of both idle and absolute session timeouts. The absolute timeout cannot be extended via refresh token exchange.

​
Limitations

​
Unsupported flows

ORTs are only available for flows that create an interactive browser session. The following flows cannot issue ORTs:
FlowReason
Device Authorization FlowSession created in browser, token used on different device
Implicit FlowOAuth spec prohibits refresh tokens in implicit flow
Resource Owner Password GrantNo browser session is created
Client Credentials FlowNo user or session involved
Custom Token ExchangeNo session to bind the token to
If you request online_access scope in any of these flows, the scope is silently ignored and no refresh token is issued.

​
Scope conflicts

You cannot request both online_access and offline_access in the same authorization request. If both scopes are included, Auth0 returns an error: 
{
  "error": "invalid_request",
  "error_description": "Cannot request both online_access and offline_access scopes"
}
Select the appropriate scope based on your use case:
  • Use online_access for browser-based applications that benefit from SSO continuity.
  • Use offline_access for applications that need tokens to work independently of the browser session.

​
Learn more