@auth0/auth0-react 2.12.0 → 2.13.0

package/dist/use-auth0.d.ts

@@ -12,7 +12,8 @@ import { Auth0ContextInterface } from './auth0-context';
  *   getAccessTokenSilently,
  *   getAccessTokenWithPopup,
  *   getIdTokenClaims,
- *   exchangeToken,
+ *   loginWithCustomTokenExchange,
+ *   exchangeToken, // deprecated - use loginWithCustomTokenExchange
  *   loginWithRedirect,
  *   loginWithPopup,
  *   logout,

package/dist/use-auth0.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-auth0.d.ts","sourceRoot":"","sources":["../src/use-auth0.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC3C,OAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,QAAA,MAAM,QAAQ,GAAI,KAAK,SAAS,IAAI,GAAG,IAAI,EACzC,8DAAsB,KACrB,qBAAqB,CAAC,KAAK,CACuB,CAAC;AAEtD,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"use-auth0.d.ts","sourceRoot":"","sources":["../src/use-auth0.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC3C,OAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,QAAA,MAAM,QAAQ,GAAI,KAAK,SAAS,IAAI,GAAG,IAAI,EACzC,8DAAsB,KACrB,qBAAqB,CAAC,KAAK,CACuB,CAAC;AAEtD,eAAe,QAAQ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "Auth0",
   "name": "@auth0/auth0-react",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Auth0 SDK for React Single Page Applications (SPA)",
   "keywords": [
     "auth0",
@@ -58,7 +58,7 @@
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.2",
     "@types/jest": "^29.5.14",
-    "@types/react": "19.2.10",
+    "@types/react": "19.2.11",
     "@types/react-dom": "19.2.3",
     "@typescript-eslint/eslint-plugin": "^8.36.0",
     "@typescript-eslint/parser": "^8.36.0",
@@ -95,6 +95,6 @@
     "react-dom": "^16.11.0 || ^17 || ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1"
   },
   "dependencies": {
-    "@auth0/auth0-spa-js": "^2.12.0"
+    "@auth0/auth0-spa-js": "^2.14.0"
   }
 }

package/src/auth0-context.tsx

@@ -93,6 +93,60 @@ export interface Auth0ContextInterface<TUser extends User = User>
   getIdTokenClaims: () => Promise<IdToken | undefined>;
 
   /**
+   * ```js
+   * await loginWithCustomTokenExchange(options);
+   * ```
+   *
+   * Exchanges an external subject token for Auth0 tokens and logs the user in.
+   * This method implements the Custom Token Exchange grant as specified in RFC 8693.
+   *
+   * The exchanged tokens are automatically cached, establishing an authenticated session.
+   * After calling this method, you can use `getUser()`, `getIdTokenClaims()`, and
+   * `getTokenSilently()` to access the user's information and tokens.
+   *
+   * @param options - The options required to perform the token exchange.
+   *
+   * @returns A promise that resolves to the token endpoint response,
+   * which contains the issued Auth0 tokens (access_token, id_token, etc.).
+   *
+   * The request includes the following parameters:
+   * - `grant_type`: "urn:ietf:params:oauth:grant-type:token-exchange"
+   * - `subject_token`: The external token to exchange
+   * - `subject_token_type`: The type identifier of the external token
+   * - `scope`: Merged scopes from the request and SDK defaults
+   * - `audience`: Target audience (defaults to SDK configuration)
+   * - `organization`: Optional organization ID/name for org-scoped authentication
+   *
+   * **Example Usage:**
+   *
+   * ```js
+   * const options = {
+   *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
+   *   subject_token_type: 'urn:acme:legacy-system-token',
+   *   scope: 'openid profile email',
+   *   audience: 'https://api.example.com',
+   *   organization: 'org_12345'
+   * };
+   *
+   * try {
+   *   const tokenResponse = await loginWithCustomTokenExchange(options);
+   *   console.log('Access token:', tokenResponse.access_token);
+   *
+   *   // User is now logged in - access user info
+   *   const user = await getUser();
+   *   console.log('Logged in user:', user);
+   * } catch (error) {
+   *   console.error('Token exchange failed:', error);
+   * }
+   * ```
+   */
+  loginWithCustomTokenExchange: (
+    options: CustomTokenExchangeOptions
+  ) => Promise<TokenEndpointResponse>;
+
+  /**
+   * @deprecated Use `loginWithCustomTokenExchange()` instead. This method will be removed in the next major version.
+   *
    * ```js
    * const tokenResponse = await exchangeToken({
    *   subject_token: 'external_token_value',
@@ -101,18 +155,20 @@ export interface Auth0ContextInterface<TUser extends User = User>
    * });
    * ```
    *
-   * Exchanges an external subject token for Auth0 tokens via a token exchange request.
+   * Exchanges an external subject token for Auth0 tokens and logs the user in.
    *
    * This method implements the token exchange grant as specified in RFC 8693.
    * It performs a token exchange by sending a request to the `/oauth/token` endpoint
    * with the external token and returns Auth0 tokens (access token, ID token, etc.).
    *
-   * The request includes the following parameters:
-   * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange"
-   * - `subject_token`: The external token to be exchanged
-   * - `subject_token_type`: A namespaced URI identifying the token type (must be under your organization's control)
-   * - `audience`: The target audience (falls back to the SDK's default audience if not provided)
-   * - `scope`: Space-separated list of scopes (merged with the SDK's default scopes)
+   * **Example:**
+   * ```js
+   * // Instead of:
+   * const tokens = await exchangeToken(options);
+   *
+   * // Use:
+   * const tokens = await loginWithCustomTokenExchange(options);
+   * ```
    *
    * @param options - The options required to perform the token exchange
    * @returns A promise that resolves to the token endpoint response containing Auth0 tokens
@@ -271,6 +327,7 @@ export const initialContext = {
   getAccessTokenSilently: stub,
   getAccessTokenWithPopup: stub,
   getIdTokenClaims: stub,
+  loginWithCustomTokenExchange: stub,
   exchangeToken: stub,
   loginWithRedirect: stub,
   loginWithPopup: stub,

package/src/auth0-provider.tsx

@@ -279,19 +279,19 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     [client]
   );
 
-  const exchangeToken = useCallback(
+  const loginWithCustomTokenExchange = useCallback(
     async (
       options: CustomTokenExchangeOptions
     ): Promise<TokenEndpointResponse> => {
       let tokenResponse;
       try {
-        tokenResponse = await client.exchangeToken(options);
+        tokenResponse = await client.loginWithCustomTokenExchange(options);
       } catch (error) {
         throw tokenError(error);
       } finally {
-        // We dispatch the standard GET_ACCESS_TOKEN_COMPLETE action here to maintain 
-        // backward compatibility and consistency with the getAccessTokenSilently flow. 
-        // This ensures the SDK's internal state lifecycle (loading/user updates) remains 
+        // We dispatch the standard GET_ACCESS_TOKEN_COMPLETE action here to maintain
+        // backward compatibility and consistency with the getAccessTokenSilently flow.
+        // This ensures the SDK's internal state lifecycle (loading/user updates) remains
         // identical regardless of whether the token was retrieved via silent auth or CTE.
         dispatch({
           type: 'GET_ACCESS_TOKEN_COMPLETE',
@@ -303,6 +303,15 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     [client]
   );
 
+  const exchangeToken = useCallback(
+    async (
+      options: CustomTokenExchangeOptions
+    ): Promise<TokenEndpointResponse> => {
+      return loginWithCustomTokenExchange(options);
+    },
+    [loginWithCustomTokenExchange]
+  );
+
   const handleRedirectCallback = useCallback(
     async (
       url?: string
@@ -352,6 +361,7 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
       getAccessTokenSilently,
       getAccessTokenWithPopup,
       getIdTokenClaims,
+      loginWithCustomTokenExchange,
       exchangeToken,
       loginWithRedirect,
       loginWithPopup,
@@ -369,6 +379,7 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     getAccessTokenSilently,
     getAccessTokenWithPopup,
     getIdTokenClaims,
+    loginWithCustomTokenExchange,
     exchangeToken,
     loginWithRedirect,
     loginWithPopup,

package/src/use-auth0.tsx

@@ -14,7 +14,8 @@ import Auth0Context, { Auth0ContextInterface } from './auth0-context';
  *   getAccessTokenSilently,
  *   getAccessTokenWithPopup,
  *   getIdTokenClaims,
- *   exchangeToken,
+ *   loginWithCustomTokenExchange,
+ *   exchangeToken, // deprecated - use loginWithCustomTokenExchange
  *   loginWithRedirect,
  *   loginWithPopup,
  *   logout,