feat: add Multi-Resource Refresh Token (MRRT) support

.github/workflows/publish-docs.yml

@@ -1,70 +1,70 @@
 name: PUBLISH DOCS
 on:
-    workflow_dispatch:
-    workflow_call:
-    # or set up your own custom triggers
+  workflow_dispatch:
+  workflow_call:
+  # or set up your own custom triggers
 permissions:
-    contents: write # allows the 'Commit' step without tokens
+  contents: write # allows the 'Commit' step without tokens
 
 jobs:
-    get_history: # create an artifact from the existing documentation builds
-        runs-on: ubuntu-latest
-        steps:
-            - name: get the gh-pages repo
-              uses: actions/checkout@v6
-              with:
-                  ref: gh-pages
+  get_history: # create an artifact from the existing documentation builds
+    runs-on: ubuntu-latest
+    steps:
+      - name: get the gh-pages repo
+        uses: actions/checkout@v6
+        with:
+          ref: gh-pages
 
-            - name: remove all symbolic links from root if present
-              run: |
-                  find . -maxdepth 1 -type l -delete
+      - name: remove all symbolic links from root if present
+        run: |
+          find . -maxdepth 1 -type l -delete
 
-            - name: tar the existing docs from root
-              run: |
-                  tar -cvf documentation.tar ./
+      - name: tar the existing docs from root
+        run: |
+          tar -cvf documentation.tar ./
 
-            - name: create a document artifact
-              uses: actions/upload-artifact@v5
-              with:
-                  name: documentation
-                  path: documentation.tar
-                  retention-days: 1
+      - name: create a document artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: documentation
+          path: documentation.tar
+          retention-days: 1
 
-    build_and_deploy: # builds the distribution and then the documentation
-        needs: get_history
-        runs-on: ubuntu-latest
-        permissions:
-            contents: write
-        steps:
-            - name: Checkout src
-              uses: actions/checkout@v6
-              with:
-                  token: ${{ github.token }}
+  build_and_deploy: # builds the distribution and then the documentation
+    needs: get_history
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout src
+        uses: actions/checkout@v6
+        with:
+          token: ${{ github.token }}
 
-            - name: Download the existing documents artifact
-              uses: actions/download-artifact@v6
-              with:
-                  name: documentation
-            - run: rm -rf ./docs # delete previous docs folder present
-            - run: mkdir ./docs # create an empty docs folder
-            - run: tar -xf documentation.tar -C ./docs
-            - run: rm -f documentation.tar
+      - name: Download the existing documents artifact
+        uses: actions/download-artifact@v6
+        with:
+          name: documentation
+      - run: rm -rf ./docs # delete previous docs folder present
+      - run: mkdir ./docs # create an empty docs folder
+      - run: tar -xf documentation.tar -C ./docs
+      - run: rm -f documentation.tar
 
-            - name: Setup
-              uses: ./.github/actions/setup
+      - name: Setup
+        uses: ./.github/actions/setup
 
-            - name: Build documents
-              run: yarn docs #set up 'docs' build script in your package.json
+      - name: Build documents
+        run: yarn docs #set up 'docs' build script in your package.json
 
-            - name: Remove all the symbolic links from docs folder
-              run: find ./docs -type l -delete
+      - name: Remove all the symbolic links from docs folder
+        run: find ./docs -type l -delete
 
-            - name: Run cleanup and manage document versions
-              run: node scripts/manage-doc-versions.js
+      - name: Run cleanup and manage document versions
+        run: node scripts/manage-doc-versions.js
 
-            - name: Deploy to GitHub Pages
-              uses: peaceiris/actions-gh-pages@v4
-              with:
-                  github_token: ${{ github.token }}
-                  publish_dir: ./docs
-                  keep_files: false
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ github.token }}
+          publish_dir: ./docs
+          keep_files: false

EXAMPLES.md

@@ -25,6 +25,12 @@
   - [Handling DPoP token migration](#handling-dpop-token-migration)
   - [Checking token type](#checking-token-type)
   - [Handling nonce errors](#handling-nonce-errors)
+- [Multi-Resource Refresh Tokens (MRRT)](#multi-resource-refresh-tokens-mrrt)
+  - [Overview](#mrrt-overview)
+  - [Prerequisites](#mrrt-prerequisites)
+  - [Using MRRT with Hooks](#using-mrrt-with-hooks)
+  - [Using MRRT with Auth0 Class](#using-mrrt-with-auth0-class)
+  - [Web Platform Configuration](#web-platform-configuration)
 - [Bot Protection](#bot-protection)
   - [Domain Switching](#domain-switching)
     - [Android](#android)
@@ -304,6 +310,128 @@ auth0.webAuth
 
 If the URL doesn't contain the expected values, an error will be raised through the provided callback.
 
+## Multi-Resource Refresh Tokens (MRRT)
+
+### MRRT Overview
+
+Multi-Resource Refresh Tokens (MRRT) allow your application to obtain access tokens for multiple APIs using a single refresh token. This is useful when your application needs to access multiple backend services, each identified by a different audience.
+
+### MRRT Prerequisites
+
+Before using MRRT, ensure:
+
+1. **MRRT is enabled on your Auth0 tenant** - Contact Auth0 support or enable it through the Auth0 Dashboard
+2. **Request `offline_access` scope during login** - This ensures a refresh token is issued
+3. **Configure your APIs in Auth0 Dashboard** - Each API you want to access should be registered with its own audience identifier
+
+### Using MRRT with Hooks
+
+```tsx
+import { useAuth0 } from 'react-native-auth0';
+
+function MyComponent() {
+  const { authorize, getApiCredentials, clearApiCredentials } = useAuth0();
+
+  const login = async () => {
+    // Login with offline_access to get a refresh token
+    await authorize({
+      scope: 'openid profile email offline_access',
+      audience: 'https://primary-api.example.com',
+    });
+  };
+
+  const getFirstApiToken = async () => {
+    try {
+      // Get credentials for the first API
+      const credentials = await getApiCredentials(
+        'https://first-api.example.com',
+        'read:data write:data'
+      );
+      console.log('First API Access Token:', credentials.accessToken);
+      console.log('Expires At:', new Date(credentials.expiresAt * 1000));
+    } catch (error) {
+      console.error('Error:', error);
+    }
+  };
+
+  const getSecondApiToken = async () => {
+    try {
+      // Get credentials for a different API using the same refresh token
+      const credentials = await getApiCredentials(
+        'https://second-api.example.com',
+        'read:reports'
+      );
+      console.log('Second API Access Token:', credentials.accessToken);
+    } catch (error) {
+      console.error('Error:', error);
+    }
+  };
+
+  const clearFirstApiCache = async () => {
+    // Clear cached credentials for a specific API
+    await clearApiCredentials('https://first-api.example.com');
+  };
+
+  return (
+    // Your UI components
+  );
+}
+```
+
+### Using MRRT with Auth0 Class
+
+```js
+import Auth0 from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_AUTH0_CLIENT_ID',
+});
+
+// Login with offline_access scope
+await auth0.webAuth.authorize({
+  scope: 'openid profile email offline_access',
+  audience: 'https://primary-api.example.com',
+});
+
+// Get credentials for a specific API
+const apiCredentials = await auth0.credentialsManager.getApiCredentials(
+  'https://first-api.example.com',
+  'read:data write:data'
+);
+
+console.log('Access Token:', apiCredentials.accessToken);
+console.log('Token Type:', apiCredentials.tokenType);
+console.log('Expires At:', apiCredentials.expiresAt);
+console.log('Scope:', apiCredentials.scope);
+
+// Clear cached credentials for a specific API
+await auth0.credentialsManager.clearApiCredentials(
+  'https://first-api.example.com'
+);
+```
+
+### Web Platform Configuration
+
+On the **web platform**, you must explicitly enable MRRT support in the `Auth0Provider`:
+
+```tsx
+import { Auth0Provider } from 'react-native-auth0';
+
+function App() {
+  return (
+    <Auth0Provider
+      domain="your-domain.auth0.com"
+      clientId="your-client-id"
+      useMrrt={true}
+      cacheLocation="localstorage"
+    >
+      <YourApp />
+    </Auth0Provider>
+  );
+}
+```
+
 ## Bot Protection
 
 If you are using the [Bot Protection](https://auth0.com/docs/anomaly-detection/bot-protection) feature and performing database login/signup via the Authentication API, you need to handle the `requires_verification` error. It indicates that the request was flagged as suspicious and an additional verification step is necessary to log the user in. That verification step is web-based, so you need to use Universal Login to complete it.

FAQ.md

@@ -391,7 +391,7 @@ function App() {
   const onLogin = async () => {
     await authorize({
       audience: AUDIENCE,
-      scope: 'openid profile email offline_access'
+      scope: 'openid profile email offline_access',
     });
   };
 
@@ -400,7 +400,7 @@ function App() {
     const credentials = await getCredentials(
       'openid profile email offline_access',
       0,
-      { audience: AUDIENCE }  // ← Must include audience here!
+      { audience: AUDIENCE } // ← Must include audience here!
     );
     console.log('JWT Access Token:', credentials.accessToken);
   };
@@ -427,15 +427,15 @@ Define your auth configuration once and reuse it:
 ```javascript
 const AUTH_CONFIG = {
   audience: 'https://your-api.example.com',
-  scope: 'openid profile email offline_access'
+  scope: 'openid profile email offline_access',
 };
 
 // Login
 await authorize(AUTH_CONFIG);
 
 // Get credentials later (include audience in parameters)
 await getCredentials(AUTH_CONFIG.scope, 0, {
-  audience: AUTH_CONFIG.audience
+  audience: AUTH_CONFIG.audience,
 });
 ```
 
@@ -444,13 +444,13 @@ await getCredentials(AUTH_CONFIG.scope, 0, {
 ```javascript
 const auth0 = new Auth0({
   domain: 'YOUR_DOMAIN',
-  clientId: 'YOUR_CLIENT_ID'
+  clientId: 'YOUR_CLIENT_ID',
 });
 
 // Login
 await auth0.webAuth.authorize({
   audience: 'https://your-api.example.com',
-  scope: 'openid profile email offline_access'
+  scope: 'openid profile email offline_access',
 });
 
 // Get credentials (must include audience)

README.md

@@ -212,9 +212,9 @@ To use the SDK with Expo, configure the app at build time by providing the `doma
 
 > :info: If you want to switch between multiple domains in your app, refer [here](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md#domain-switching)
 
-| API          | Description                                                                                                                                                                                                                                                                  |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| domain       | Mandatory: Provide the Auth0 domain that can be found at the [Application Settings](https://manage.auth0.com/#/applications)                                                                                                                                                 |
+| API          | Description                                                                                                                                                                                                                                                                                                                         |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| domain       | Mandatory: Provide the Auth0 domain that can be found at the [Application Settings](https://manage.auth0.com/#/applications)                                                                                                                                                                                                        |
 | customScheme | Optional: Custom scheme to build the callback URL with. The value provided here should be passed to the `customScheme` option parameter of the `authorize` and `clearSession` methods. The custom scheme should be a unique, all lowercase value with no special characters. To use Android App Links, set this value to `"https"`. |
 
 **Note:** When using `customScheme: "https"` for Android App Links, the plugin will automatically add `android:autoVerify="true"` to the intent-filter in your Android manifest to enable automatic verification of App Links.

android/build.gradle

@@ -96,7 +96,7 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "androidx.browser:browser:1.2.0"
-  implementation 'com.auth0.android:auth0:3.10.0'
+  implementation 'com.auth0.android:auth0:3.11.0'
 }
 
 if (isNewArchitectureEnabled()) {