Configure and Implement Multi-Resource Refresh Token

Multi-Resource Refresh Token support is currently available in Early Access. To learn more about Auth0’s product release cycle, review Product Release Stages.

Configure applications for MRRT

To use Multi-Resource Refresh Tokens (MRRT), configure your application’s refresh token policies using the Auth0 Management API. These policies will specify which API and scopes the application is allowed to request during a refresh token exchange.

You can define MRRT policies in the refresh_token.policies property of the application.

Property	Type	Description
audience	string	The Auth0 API identifier of the application that will have access to using the refresh token.
scope	Array of strings	The list of scopes allowed when requesting an access token for the specified audience. The scope must be equal to or narrower than the scopes defined on the API.

The audience and scope properties must correspond to an existing application in your tenant, otherwise the refresh token exchange will silently ignore them.

For existing applications, make a PATCH call to the Update a Client endpoint. To create a new application, make a POST call to the Create a Client endpoint:

cURL

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/clients//{yourClientId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
  --header 'content-type: application/json' \
  --data '{
  "refresh_token": {
    "expiration_type": "expiring",
    "rotation_type": "rotating",
    "token_lifetime": 31557600,
    "idle_token_lifetime": 2592000,
    "leeway": 0,
    "infinite_token_lifetime": false,
    "infinite_idle_token_lifetime": false,
    "policies": [
      {
        "audience": "https://api.example.com",
        "scope": ["read:data"]
      },
      {
        "audience": "https://billing.example.com",
        "scope": ["read:billing"]
      }
    ]
  }
}'

Sample response:

{
  "client_id": "abc123xyz",
  "name": "My Native App",
  "refresh_token": {
    "rotation_type": "rotating",
    "policies": [
      {
        "audience": "https://api.example.com",
        "scope": ["read:data"]
      },
      {
        "audience": "https://billing.example.com",
        "scope": ["read:billing"]
      }
    ]
  }
}

Implement multi-resource refresh token

Once you configure your application’s refresh token with MRRT policies, you can start to  exchange a single refresh token for access tokens across multiple APIs. To facilitate this, your application needs to initiate a login flow using either the Authorization Code Flow or the Resource Owner Password Grant.

Step 1: Authenticate and request a refresh token

To receive a refresh token, include the offline_access scope when initiating the authentication request. To learn more, read Get Refresh Tokens.

If you do not receive a refresh token, confirm that:

• The API has Allow Offline Access enabled in its settings.
• offline_access is included in the scope.
• The audience used in the request matches a configured API in your tenant.

Step 2: Exchange the refresh token for a different API

Once the refresh token is issued, you can request access tokens for any API and scopes defined in both the initial authentication and the MRRT policy. For example:

cURL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/json' \
  --data '{
  "grant_type": "refresh_token",
  "client_id": "{yourClientId}",
  "refresh_token": "${refreshToken}",
  "audience": "https://billing.example.com",
  "scope": "read:billing write:billing"
}'

 To learn more, read Use Refresh tokens.

If you are using the Auth0 Swift SDK, you can exchange the refresh token using the following code:

credentialsManager.apiCredentials(forAudience: "https://example.com/me",
                                  scope: "create:me:authentication_methods") { result in
    switch result {
    case .success(let apiCredentials):
        print("Obtained API credentials: \(apiCredentials)")
    case .failure(let error):
        print("Failed with: \(error)")
    }
}

To learn more, read Auth0 Swift SDK.

If you are using the Auth0 Android SDK, you can exchange the refresh token using the following code:

credentialsManager.getApiCredentials(
    audience = "https://example.com/me", scope = " create:me:authentication_methods",
    callback = object : Callback<APICredentials, CredentialsManagerException> {
        override fun onSuccess(result: APICredentials) {
            print("Obtained API credentials: $result")
        }
        override fun onFailure(error: CredentialsManagerException) {
            print("Failed with: $error")
        }
    })

To learn more, read Auth0 Android SDK.

Step 3: Call the API using the access token

Use the access token to call the secured API using the Bearer HTTP authorization scheme. To learn more, read Use Access Tokens.

You can decode the access token on jwt.io to verify:

• The aud claim matches the requested API. (for example: https://billing.example.com).
• The scope claim includes only permitted values.

Use Multi-resource refresh token with Actions

Using MRRT with Actions allows you to configure dynamic decision-making based on the application’s MRRT policies. To facilitate this, post-login Actions features the event.client.refresh_token.policies object that provides relevant information including audience and scope.

You can use the event.client.refresh_token.policies object to evaluate the application’s audience and scope, when issuing or exchanging a refresh token, and to ensure precise control over API access and scopes.

exports.onExecutePostLogin = async (event, api) => {
  // return the list of allowed APIs in the client
  const allowedAPIsInTheClient = event.client.refresh_token?.policies;

  if(allowedAPIsInTheClient?.some(policy => policy?.audience?.includes('https://myapi'))){
    // custom logic
  }
};

Evaluation logic

MRRT acts as an extension of the original authentication, not a replacement. When exchanging a refresh token, Auth0 evaluates the exchange request using the following logic:

• If the audience parameter is omitted, Auth0 returns an access token with the original audience and any of its additional scopes configured in the MRRT policy.
• If a new audience parameter is specified, Auth0 verifies that the audience is included in the MRRT policy and returns an access token for the new audience with its configured scopes.
• If the scope parameter is omitted, Auth0 combines all allowed scopes from the original request and the MRRT policy.
• If a new scope parameter is specified, Auth0 validates the requested scopes and returns an access token with the scopes included in the MRTT policy. Invalid or unauthorized scopes requested are silently ignored.
• If the audience parameter is the same as from the original request, Auth0 applies the MRRT policy and returns an access token for the audience with all MRRT configured scopes and original authentication scopes.

MRRT allows you to extend user access to new APIs without issuing new refresh tokens or requiring user login again.

Examples

A user logs in requesting the following audience and scope:

{
"audience": "https://api.example.com",  
"scope": "openid profile read:messages"
}

The application’s MRRT policy is configured to add an additional scope:

{
  "audience": "https://api.example.com",
  "scope": ["write:messages"]
}

A refresh token exchange using the same audience and no scopes would result in an access token containing all configured scopes:

{
  "aud": "https://api.example.com",
  "scope": "openid profile read:messages write:messages"
}