Skip to main content

​
Configure ORTs

Online Refresh Tokens (ORTs) must be enabled at the API (Resource Server) level using the Auth0 Dashboard or the Management API.

​
Configure using the Dashboard

  1. Navigate to Dashboard > Applications > API.
  2. Select the API you want to configure.
  3. In the Settings tab, enable the Allow Online Access toggle.
    Dashboard Applications APIs Settings Allow Online Access
  4. Select Save.
To review and configure idle timeout and absolute lifetime values for sessions, review the Tenant Session Expiration settings. To learn more, read Configure Session lifetime.

​
Configure using the Management API

To enable ORTs, make a PATCH call to the Update Resource Server endpoint: 
curl --request PATCH \
  --url 'https://<YOUR_DOMAIN>/api/v2/resource-servers/<YOUR_RESOURCE_SERVER_ID>' \
  --header 'authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{"allow_online_access": true}'
To verify the configuration, make a GET call to the resource server: 
curl --request GET \
  --url 'https://<YOUR_DOMAIN>/api/v2/resource-servers/<YOUR_RESOURCE_SERVER_ID>' \
  --header 'authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>'
The response includes the allow_online_access property: 
{
  "id": "resource-server-id",
  "name": "My API",
  "identifier": "https://my-api.example.com",
  "allow_online_access": true,
  ...
}

​
Get an ORT

To get an ORT, include the online_access scope in your authorization request using the Authorization Code Flow or Authorization Code Flow with PKCE. 
https://<YOUR_DOMAIN>/authorize \
    audience=<YOUR_API_AUDIENCE> \
    scope=openid profile online_access \
    response_type=code \
    client_id=<YOUR_CLIENT_ID> \
    redirect_uri=<https://YOUR_APP/callback> \
    state=<OPAQUE_VALUE>
After the user authenticates, exchange the authorization code for tokens: 
curl --request POST \
  --url 'https://<YOUR_DOMAIN>/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'code=<YOUR_AUTHORIZATION_CODE>' \
  --data 'redirect_uri=<https://YOUR_APP/callback>' \
  --data 'code_verifier=<YOUR_CODE_VERIFIER>'
The token response includes the ORT: 
{
  "access_token": "eyJ...",
  "id_token": "eyJ...",
  "refresh_token": "ORT...",
  "token_type": "Bearer",
  "expires_in": 86400
}
ORTs are prefixed with ORT to distinguish them from refresh tokens. However, you should treat the token as opaque and not rely on its internal structure.

​
Use an ORT

Exchange the ORT for a new access token when the current access token expires or is about to expire: 
curl --request POST \
  --url 'https://<YOUR_DOMAIN>/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'refresh_token=<YOUR_ONLINE_REFRESH_TOKEN>'
The response contains a new access token. If your request includes an openid scope, the response includes a new ID token: 
{
  "access_token": "eyJ...",
  "id_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 86400
}
Auth0 does not issue a new refresh_token and as ORTs do not rotate, you continue using the same ORT for subsequent exchanges.

​
Session extension behavior

Each successful token exchange:
  • Resets the session idle timeout: The idle timeout is restored to its full duration.
  • Does not extend absolute lifetime: The session’s absolute expiration remains unchanged.
  • Maintains SSO: Other applications can get tokens via SSO as long as the session is alive.

​
Revoke an ORT

When you revoke an ORT, it terminates the entire Auth0 session, not just the token. This invalidates all ORTs bound to that session and ends SSO for the user. 
curl --request POST \
  --url 'https://<YOUR_DOMAIN>/oauth/revoke' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'token=<YOUR_ONLINE_REFRESH_TOKEN>'

​
Use ORTs with Actions

You can use ORTs with Auth0 Actions and the post-login trigger. Using Actions you can:
  • Use the event.refresh_token object to determine if the token is an ORT.
  • Access session specific data using the event.session object to make decisions based on the current session state
exports.onExecutePostLogin = async (event, api) => {
  // Check if token is an Online refresh token
  
  if (event.refresh_token?.access == 'online') {
    // The token is an ORT, you can then reference event.session and api.session
    console.log('Exchanging Online Refresh Token bound to Session ID: ', event.session?.id);
    // Pull the session metadata and add it in the tokens
    // Assuming the session metadata was stored previously
    const importantInformation = event.session?.metadata?.importantInformation;
    api.accessToken.setCustomClaim('info', importantInformation);
    api.idToken.setCustomClaim('info', importantInformation);
  }
};
Auth0 revokes the entire user session rather than just the token, when the api.refreshToken.revoke() method is used with an ORT.

​
Learn more