> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to configure and implement multi-resource refresh token

# Configure and Implement Multi-Resource Refresh Token

export const AuthCodeGroup = ({children, dropdown}) => {
  const [processedChildren, setProcessedChildren] = useState(children);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      unsubscribe = window.autorun(() => {
        const processChildren = node => {
          if (typeof node === "string") {
            let processedNode = node;
            for (const [key, value] of window.rootStore.variableStore.values.entries()) {
              const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
              processedNode = processedNode.replaceAll(new RegExp(escapedKey, "g"), value);
            }
            return processedNode;
          } else if (Array.isArray(node)) {
            return node.map(processChildren);
          } else if (node && node.props && node.props.children) {
            return {
              ...node,
              props: {
                ...node.props,
                children: processChildren(node.props.children)
              }
            };
          }
          return node;
        };
        setProcessedChildren(processChildren(children));
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  return <CodeGroup dropdown={dropdown}>{processedChildren}</CodeGroup>;
};

export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
  const [displayText, setDisplayText] = useState(children);
  const [copyText, setCopyText] = useState(children);
  const wrapperRef = React.useRef(null);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      if (!window.autorun || !window.rootStore) {
        return;
      }
      unsubscribe = window.autorun(() => {
        let processedChildrenForDisplay = children;
        let processedChildrenForCopy = children;
        for (const [key, value] of window.rootStore.variableStore.values.entries()) {
          const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
          let displayValue = value;
          if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") {
            displayValue = value.substring(0, 3) + "*****MASKED*****";
          }
          processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue);
          processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value);
        }
        setDisplayText(processedChildrenForDisplay);
        setCopyText(processedChildrenForCopy);
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  useEffect(() => {
    if (!wrapperRef.current) return;
    const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard);
    let isOverriding = false;
    const handleClick = e => {
      const button = e.target.closest('[data-testid="copy-code-button"]');
      if (!button || !wrapperRef.current.contains(button)) return;
      isOverriding = true;
      navigator.clipboard.writeText = text => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
          return originalWriteText(copyText);
        }
        return originalWriteText(text);
      };
      setTimeout(() => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
        }
      }, 100);
    };
    const wrapper = wrapperRef.current;
    wrapper.addEventListener('click', handleClick, true);
    return () => {
      wrapper.removeEventListener('click', handleClick, true);
      if (navigator.clipboard.writeText !== originalWriteText) {
        navigator.clipboard.writeText = originalWriteText;
      }
    };
  }, [copyText]);
  return <div ref={wrapperRef}>
      <CodeBlock filename={filename} icon={icon} language={language} lines highlight={highlight}>
        {displayText}
      </CodeBlock>
    </div>;
};

## Configure applications for MRRT

To use Multi-Resource <Tooltip tip="Refresh Token: Token used to obtain a renewed Access Token without forcing users to log in again." cta="View Glossary" href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> (MRRT), configure your application’s refresh token policies using the Auth0 [Management API](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id). 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](/docs/get-started/apis/api-settings#general-settings) 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. |

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The audience and scope properties must correspond to an existing application in your tenant, otherwise the refresh token exchange will silently ignore them.
</Callout>

For existing applications, make a PATCH call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint. To create a new application, make a POST call to the [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  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"]
        }
      ]
    }
  }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/clients//{yourClientId}");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{
    "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"]
        }
      ]
    }
  }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/clients//{yourClientId}"

  	payload := strings.NewReader("{
    "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"]
        }
      ]
    }
  }")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/clients//{yourClientId}")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .header("content-type", "application/json")
    .body("{
    "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"]
        }
      ]
    }
  }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/clients//{yourClientId}',
    headers: {
      authorization: 'Bearer {yourMgmtApiAccessToken}',
      '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']}
        ]
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/clients//{yourClientId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{
    "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"]
        }
      ]
    }
  }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{
    "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"]
        }
      ]
    }
  }"

  headers = {
      'authorization': "Bearer {yourMgmtApiAccessToken}",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/clients//{yourClientId}", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/clients//{yourClientId}")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Patch.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{
    "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"]
        }
      ]
    }
  }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

Sample response:

```json lines theme={null}
{
  "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 <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=access+tokens">access tokens</Tooltip> across multiple APIs.
To facilitate this, your application needs to initiate a login flow using either the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) or the [Resource Owner Password Grant](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-rop-flow).

### 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](/docs/secure/tokens/refresh-tokens/get-refresh-tokens).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  If you do not receive a refresh token, confirm that:

  * The API has [Allow Offline Access](/docs/get-started/apis/api-settings#access-settings) enabled in its settings.
  * `offline_access` is included in the scope.
  * The `audience` used in the request matches a configured API in your tenant.
</Callout>

### 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:

<AuthCodeGroup>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'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'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

 To learn more, read [Use Refresh tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens).

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

```swift lines theme={null}
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](https://github.com/auth0/Auth0.swift/blob/master/EXAMPLES.md#api-credentials-ea).

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

```kotlin lines theme={null}
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](https://github.com/auth0/Auth0.Android/blob/main/EXAMPLES.md#api-credentials-ea).

### Step 3: Call the API using the access token

Use the access token to call the secured API using the [Bearer HTTP authorization scheme](https://datatracker.ietf.org/doc/html/rfc6750). To learn more, read [Use Access Tokens](/docs/secure/tokens/access-tokens/use-access-tokens).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  You can decode the access token on [jwt.io](https://jwt.io) to verify:

  * The `aud` claim matches the requested API. (for example: [https://billing.example.com](https://billing.example.com)).
  * The `scope` claim includes only permitted values.
</Callout>

## Use Multi-resource refresh token with Actions

Using MRRT with [Actions](/docs/customize/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`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) object that provides relevant information including <Tooltip tip="Audience: Unique identifier of the audience for an issued token. Named aud in a token, its value contains the ID of either an application (Client ID) for an ID Token or an API (API Identifier) for an Access Token." cta="View Glossary" href="/docs/glossary?term=audience">audience</Tooltip> 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.

```js lines theme={null}
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:

```json lines theme={null}
{
"audience": "https://api.example.com",  
"scope": "openid profile read:messages"
}
```

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

```json lines theme={null}
{
  "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:

```json lines theme={null}
{
  "aud": "https://api.example.com",
  "scope": "openid profile read:messages write:messages"
}
```