From 53740e87ce02770dbe736a1296b3dccf17f58026 Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Tue, 13 Jan 2026 10:48:53 +0530
Subject: [PATCH 1/8] feat: implement Custom Token Exchange (RFC 8693)
 functionality

---
 EXAMPLES.md                                   | 95 +++++++++++++++++++
 .../java/com/auth0/react/A0Auth0Module.kt     | 34 +++++++
 .../oldarch/com/auth0/react/A0Auth0Spec.kt    | 11 +++
 ios/A0Auth0.mm                                | 10 ++
 ios/NativeBridge.swift                        | 24 +++++
 src/Auth0.ts                                  | 31 +++++-
 src/core/interfaces/IAuth0Client.ts           | 18 +++-
 src/hooks/Auth0Context.ts                     | 25 +++++
 src/hooks/Auth0Provider.tsx                   |  9 ++
 .../native/adapters/NativeAuth0Client.ts      | 43 +++++++--
 src/platforms/native/bridge/INativeBridge.ts  | 19 ++++
 .../native/bridge/NativeBridgeManager.ts      | 18 ++++
 src/platforms/web/adapters/WebAuth0Client.ts  | 48 +++++++++-
 src/specs/NativeA0Auth0.ts                    | 12 +++
 src/types/parameters.ts                       | 49 ++++++++++
 15 files changed, 435 insertions(+), 11 deletions(-)

diff --git a/EXAMPLES.md b/EXAMPLES.md
index 62a11e86..d663f413 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -37,6 +37,11 @@
   - [Using MRRT with Hooks](#using-mrrt-with-hooks)
   - [Using MRRT with Auth0 Class](#using-mrrt-with-auth0-class)
   - [Web Platform Configuration](#web-platform-configuration)
+- [Custom Token Exchange (RFC 8693)](#custom-token-exchange-rfc-8693)
+  - [Using Custom Token Exchange with Hooks](#using-custom-token-exchange-with-hooks)
+  - [Using Custom Token Exchange with Auth0 Class](#using-custom-token-exchange-with-auth0-class)
+  - [With Organization Context](#with-organization-context)
+  - [Subject Token Type Requirements](#subject-token-type-requirements)
 - [Native to Web SSO (Early Access)](#native-to-web-sso-early-access)
   - [Overview](#native-to-web-sso-overview)
   - [Prerequisites](#native-to-web-sso-prerequisites)
@@ -563,6 +568,96 @@ function App() {
 }
 ```
 
+## Custom Token Exchange (RFC 8693)
+
+Custom Token Exchange allows you to exchange external identity provider tokens for Auth0 tokens using the [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) specification. This enables scenarios where users authenticate with an external system and that token needs to be exchanged for Auth0 tokens.
+
+> ⚠️ **Important**: The external token must be validated in Auth0 Actions using cryptographic verification. See the [Auth0 Custom Token Exchange documentation](https://auth0.com/docs/authenticate/login/custom-token-exchange) for setup instructions.
+
+### Using Custom Token Exchange with Hooks
+
+```typescript
+import React from 'react';
+import { Button, Alert } from 'react-native';
+import { useAuth0 } from 'react-native-auth0';
+
+function TokenExchangeScreen() {
+  const { customTokenExchange, user, error } = useAuth0();
+
+  const handleExchange = async () => {
+    try {
+      // Exchange an external token for Auth0 tokens
+      const credentials = await customTokenExchange({
+        subjectToken: 'token-from-external-provider',
+        subjectTokenType: 'urn:acme:legacy-system-token',
+        scope: 'openid profile email',
+        audience: 'https://api.example.com',
+      });
+
+      Alert.alert('Success', `Logged in as ${user?.name}`);
+    } catch (e) {
+      console.error('Token exchange failed:', e);
+    }
+  };
+
+  return <Button onPress={handleExchange} title="Exchange Token" />;
+}
+```
+
+### Using Custom Token Exchange with Auth0 Class
+
+```typescript
+import Auth0 from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_CLIENT_ID',
+});
+
+async function exchangeExternalToken(externalToken: string) {
+  try {
+    const credentials = await auth0.customTokenExchange({
+      subjectToken: externalToken,
+      subjectTokenType: 'urn:acme:legacy-system-token',
+      audience: 'https://api.example.com',
+      scope: 'openid profile email',
+    });
+
+    console.log('Exchange successful:', credentials);
+    return credentials;
+  } catch (error) {
+    console.error('Exchange failed:', error);
+    throw error;
+  }
+}
+```
+
+### With Organization Context
+
+Exchange tokens within a specific organization context:
+
+```typescript
+const credentials = await customTokenExchange({
+  subjectToken: 'external-provider-token',
+  subjectTokenType: 'urn:acme:legacy-system-token',
+  organization: 'org_123', // or organization name
+  scope: 'openid profile email',
+});
+```
+
+### Subject Token Type Requirements
+
+The `subjectTokenType` must be a namespaced URI under your organization's control. The following patterns are forbidden:
+
+- `urn:ietf:params:oauth:*` (IETF reserved)
+- `https://auth0.com/*` (Auth0 reserved)
+- `urn:auth0:*` (Auth0 reserved)
+
+Valid examples:
+
+- `urn:acme:legacy-system-token`
+- `https://yourcompany.com/tokens/legacy`
+
 ## Native to Web SSO (Early Access)
 
 > ⚠️ **Early Access Feature**: Native to Web SSO is currently available in Early Access. To use this feature, you must have an Enterprise plan. For more information, see [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
diff --git a/android/src/main/java/com/auth0/react/A0Auth0Module.kt b/android/src/main/java/com/auth0/react/A0Auth0Module.kt
index 9cd830fa..35ca57f7 100644
--- a/android/src/main/java/com/auth0/react/A0Auth0Module.kt
+++ b/android/src/main/java/com/auth0/react/A0Auth0Module.kt
@@ -464,6 +464,40 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
         )
     }
 
+    @ReactMethod
+    override fun customTokenExchange(
+        subjectToken: String,
+        subjectTokenType: String,
+        audience: String?,
+        scope: String?,
+        organization: String?,
+        promise: Promise
+    ) {
+        val authClient = AuthenticationAPIClient(auth0!!)
+        if (useDPoP) {
+            authClient.useDPoP(reactContext)
+        }
+        
+        val finalScope = scope ?: "openid profile email"
+        
+        authClient.customTokenExchange(
+            subjectToken = subjectToken,
+            subjectTokenType = subjectTokenType,
+            audience = audience,
+            scope = finalScope,
+            organization = organization
+        ).start(object : com.auth0.android.callback.Callback<Credentials, AuthenticationException> {
+            override fun onSuccess(result: Credentials) {
+                val map = CredentialsParser.toMap(result)
+                promise.resolve(map)
+            }
+
+            override fun onFailure(error: AuthenticationException) {
+                handleError(error, promise)
+            }
+        })
+    }
+
     override fun onActivityResult(activity: Activity, requestCode: Int, resultCode: Int, data: Intent?) {
         // No-op
     }
diff --git a/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt b/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
index ec052015..62ea00e0 100644
--- a/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
+++ b/android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
@@ -108,4 +108,15 @@ abstract class A0Auth0Spec(context: ReactApplicationContext) : ReactContextBaseJ
     @ReactMethod
     @DoNotStrip
     abstract fun getSSOCredentials(parameters: ReadableMap?, headers: ReadableMap?, promise: Promise)
+
+    @ReactMethod
+    @DoNotStrip
+    abstract fun customTokenExchange(
+        subjectToken: String,
+        subjectTokenType: String,
+        audience: String?,
+        scope: String?,
+        organization: String?,
+        promise: Promise
+    )
 }
\ No newline at end of file
diff --git a/ios/A0Auth0.mm b/ios/A0Auth0.mm
index ffe6a4c1..901bef8f 100644
--- a/ios/A0Auth0.mm
+++ b/ios/A0Auth0.mm
@@ -167,6 +167,16 @@ - (dispatch_queue_t)methodQueue
     [self.nativeBridge getSSOCredentialsWithParameters:parameters headers:headers resolve:resolve reject:reject];
 }
 
+RCT_EXPORT_METHOD(customTokenExchange:(NSString *)subjectToken
+                  subjectTokenType:(NSString *)subjectTokenType
+                  audience:(NSString * _Nullable)audience
+                  scope:(NSString * _Nullable)scope
+                  organization:(NSString * _Nullable)organization
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    [self.nativeBridge customTokenExchangeWithSubjectToken:subjectToken subjectTokenType:subjectTokenType audience:audience scope:scope organization:organization resolve:resolve reject:reject];
+}
+
 
 
 
diff --git a/ios/NativeBridge.swift b/ios/NativeBridge.swift
index 7e6c8f0f..0fd099d1 100644
--- a/ios/NativeBridge.swift
+++ b/ios/NativeBridge.swift
@@ -378,6 +378,30 @@ public class NativeBridge: NSObject {
         resolve(credentialsManager.clear(forAudience: audience, scope: scope))
     }
     
+    @objc public func customTokenExchange(subjectToken: String, subjectTokenType: String, audience: String?, scope: String?, organization: String?, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+        var auth = Auth0.authentication(clientId: self.clientId, domain: self.domain)
+        if self.useDPoP {
+            auth = auth.useDPoP()
+        }
+        
+        let finalScope = scope ?? "openid profile email"
+        
+        auth.customTokenExchange(
+            subjectToken: subjectToken,
+            subjectTokenType: subjectTokenType,
+            audience: audience,
+            scope: finalScope,
+            organization: organization
+        ).start { result in
+            switch result {
+            case .success(let credentials):
+                resolve(credentials.asDictionary())
+            case .failure(let error):
+                reject(error.code, error.localizedDescription, error)
+            }
+        }
+    }
+    
     @objc public func getClientId() -> String {
         return clientId
     }
diff --git a/src/Auth0.ts b/src/Auth0.ts
index d9276368..7bdf9ac2 100644
--- a/src/Auth0.ts
+++ b/src/Auth0.ts
@@ -1,7 +1,12 @@
 import type { IAuth0Client } from './core/interfaces/IAuth0Client';
 import type { TokenType } from './types/common';
 import { Auth0ClientFactory } from './factory/Auth0ClientFactory';
-import type { Auth0Options, DPoPHeadersParams } from './types';
+import type {
+  Auth0Options,
+  DPoPHeadersParams,
+  CustomTokenExchangeParameters,
+  Credentials,
+} from './types';
 
 /**
  * The main Auth0 client class.
@@ -92,6 +97,30 @@ class Auth0 {
   getDPoPHeaders(params: DPoPHeadersParams) {
     return this.client.getDPoPHeaders(params);
   }
+
+  /**
+   * Performs a Custom Token Exchange using RFC 8693.
+   * Exchanges an external identity provider token for Auth0 tokens.
+   *
+   * @param parameters The token exchange parameters.
+   * @returns A promise resolving with Auth0 credentials.
+   *
+   * @example
+   * ```typescript
+   * const credentials = await auth0.customTokenExchange({
+   *   subjectToken: 'external-idp-token',
+   *   subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
+   *   audience: 'https://api.example.com',
+   *   scope: 'openid profile email',
+   *   organization: 'org_abc123'
+   * });
+   * ```
+   */
+  customTokenExchange(
+    parameters: CustomTokenExchangeParameters
+  ): Promise<Credentials> {
+    return this.client.customTokenExchange(parameters);
+  }
 }
 
 export default Auth0;
diff --git a/src/core/interfaces/IAuth0Client.ts b/src/core/interfaces/IAuth0Client.ts
index db42feab..f54cb58b 100644
--- a/src/core/interfaces/IAuth0Client.ts
+++ b/src/core/interfaces/IAuth0Client.ts
@@ -2,7 +2,12 @@ import type { IWebAuthProvider } from './IWebAuthProvider';
 import type { ICredentialsManager } from './ICredentialsManager';
 import type { IAuthenticationProvider } from './IAuthenticationProvider';
 import type { IUsersClient } from './IUsersClient';
-import type { DPoPHeadersParams, TokenType } from '../../types';
+import type {
+  DPoPHeadersParams,
+  TokenType,
+  CustomTokenExchangeParameters,
+  Credentials,
+} from '../../types';
 
 /**
  * The primary interface for the Auth0 client.
@@ -58,4 +63,15 @@ export interface IAuth0Client {
    * ```
    */
   getDPoPHeaders(params: DPoPHeadersParams): Promise<Record<string, string>>;
+
+  /**
+   * Performs a Custom Token Exchange using RFC 8693.
+   * Exchanges an external identity provider token for Auth0 tokens.
+   *
+   * @param parameters The token exchange parameters.
+   * @returns A promise resolving with Auth0 credentials.
+   */
+  customTokenExchange(
+    parameters: CustomTokenExchangeParameters
+  ): Promise<Credentials>;
 }
diff --git a/src/hooks/Auth0Context.ts b/src/hooks/Auth0Context.ts
index 824d894a..80606697 100644
--- a/src/hooks/Auth0Context.ts
+++ b/src/hooks/Auth0Context.ts
@@ -16,6 +16,7 @@ import type {
   LoginOtpParameters,
   LoginRecoveryCodeParameters,
   ExchangeNativeSocialParameters,
+  CustomTokenExchangeParameters,
   RevokeOptions,
   ResetPasswordParameters,
   MfaChallengeResponse,
@@ -178,6 +179,29 @@ export interface Auth0ContextInterface extends AuthState {
     parameters: ExchangeNativeSocialParameters
   ) => Promise<Credentials>;
 
+  /**
+   * Exchanges an external identity provider token for Auth0 tokens.
+   * Uses RFC 8693 OAuth 2.0 Token Exchange specification.
+   *
+   * @param parameters The token exchange parameters.
+   * @returns A promise that resolves with the user's Auth0 credentials.
+   * @throws {AuthError} If the token exchange fails.
+   *
+   * @example
+   * ```typescript
+   * const credentials = await customTokenExchange({
+   *   subjectToken: 'external-provider-token',
+   *   subjectTokenType: 'urn:acme:legacy-system-token',
+   *   scope: 'openid profile email',
+   *   audience: 'https://api.example.com',
+   *   organization: 'org_123'
+   * });
+   * ```
+   */
+  customTokenExchange: (
+    parameters: CustomTokenExchangeParameters
+  ) => Promise<Credentials>;
+
   /**
    * Sends a verification code to the user's email.
    * @param parameters The parameters for sending the email code.
@@ -346,6 +370,7 @@ const initialContext: Auth0ContextInterface = {
   createUser: stub,
   authorizeWithRecoveryCode: stub,
   authorizeWithExchangeNativeSocial: stub,
+  customTokenExchange: stub,
   sendEmailCode: stub,
   sendSMSCode: stub,
   authorizeWithEmail: stub,
diff --git a/src/hooks/Auth0Provider.tsx b/src/hooks/Auth0Provider.tsx
index 918f4848..fab641d0 100644
--- a/src/hooks/Auth0Provider.tsx
+++ b/src/hooks/Auth0Provider.tsx
@@ -21,6 +21,7 @@ import type {
   LoginOtpParameters,
   LoginRecoveryCodeParameters,
   ExchangeNativeSocialParameters,
+  CustomTokenExchangeParameters,
   RevokeOptions,
   ResetPasswordParameters,
   MfaChallengeResponse,
@@ -307,6 +308,12 @@ export const Auth0Provider = ({
     [client, loginFlow]
   );
 
+  const customTokenExchange = useCallback(
+    (parameters: CustomTokenExchangeParameters) =>
+      loginFlow(client.customTokenExchange(parameters)),
+    [client, loginFlow]
+  );
+
   const sendEmailCode = useCallback(
     (parameters: PasswordlessEmailParameters) =>
       voidFlow(client.auth.passwordlessWithEmail(parameters)),
@@ -400,6 +407,7 @@ export const Auth0Provider = ({
       resetPassword,
       authorizeWithExchange,
       authorizeWithExchangeNativeSocial,
+      customTokenExchange,
       sendEmailCode,
       authorizeWithEmail,
       sendSMSCode,
@@ -428,6 +436,7 @@ export const Auth0Provider = ({
       resetPassword,
       authorizeWithExchange,
       authorizeWithExchangeNativeSocial,
+      customTokenExchange,
       sendEmailCode,
       authorizeWithEmail,
       sendSMSCode,
diff --git a/src/platforms/native/adapters/NativeAuth0Client.ts b/src/platforms/native/adapters/NativeAuth0Client.ts
index 91803ecc..28f84a1b 100644
--- a/src/platforms/native/adapters/NativeAuth0Client.ts
+++ b/src/platforms/native/adapters/NativeAuth0Client.ts
@@ -4,7 +4,11 @@ import type {
   IUsersClient,
 } from '../../../core/interfaces';
 import type { NativeAuth0Options } from '../../../types/platform-specific';
-import type { DPoPHeadersParams } from '../../../types';
+import type {
+  DPoPHeadersParams,
+  CustomTokenExchangeParameters,
+  Credentials,
+} from '../../../types';
 import { NativeWebAuthProvider } from './NativeWebAuthProvider';
 import { NativeCredentialsManager } from './NativeCredentialsManager';
 import { type INativeBridge, NativeBridgeManager } from '../bridge';
@@ -25,6 +29,7 @@ export class NativeAuth0Client implements IAuth0Client {
   private readonly tokenType: TokenType;
   private readonly bridge: INativeBridge;
   private readonly baseUrl: string;
+  private guardedBridge!: INativeBridge;
   private readonly getDPoPHeadersForOrchestrator?: (
     params: DPoPHeadersParams
   ) => Promise<Record<string, string>>;
@@ -53,6 +58,14 @@ export class NativeAuth0Client implements IAuth0Client {
       ? getDPoPHeadersForOrchestrator
       : undefined;
 
+    this.ready = this.initialize(bridge, options);
+
+    // The adapters are now constructed with a "proxied" bridge that
+    // automatically awaits the `ready` promise before any call.
+    const guardedBridge = this.createGuardedBridge(bridge);
+    this.guardedBridge = guardedBridge;
+
+    // Use AuthenticationOrchestrator directly for standard auth methods
     this.auth = new AuthenticationOrchestrator({
       clientId: options.clientId,
       httpClient: this.httpClient,
@@ -61,11 +74,6 @@ export class NativeAuth0Client implements IAuth0Client {
       getDPoPHeaders: useDPoP ? getDPoPHeadersForOrchestrator : undefined,
     });
 
-    this.ready = this.initialize(bridge, options);
-
-    // The adapters are now constructed with a "proxied" bridge that
-    // automatically awaits the `ready` promise before any call.
-    const guardedBridge = this.createGuardedBridge(bridge);
     this.webAuth = new NativeWebAuthProvider(guardedBridge, options.domain);
     this.credentialsManager = new NativeCredentialsManager(guardedBridge);
   }
@@ -153,4 +161,27 @@ export class NativeAuth0Client implements IAuth0Client {
 
     return guarded as INativeBridge;
   }
+
+  /**
+   * Performs a Custom Token Exchange using RFC 8693.
+   * Exchanges an external identity provider token for Auth0 tokens.
+   *
+   * This method delegates directly to the native SDK bridge.
+   *
+   * @param parameters The token exchange parameters.
+   * @returns A promise resolving with Auth0 credentials.
+   */
+  async customTokenExchange(
+    parameters: CustomTokenExchangeParameters
+  ): Promise<Credentials> {
+    const { subjectToken, subjectTokenType, audience, scope, organization } =
+      parameters;
+    return this.guardedBridge.customTokenExchange(
+      subjectToken,
+      subjectTokenType,
+      audience,
+      scope,
+      organization
+    );
+  }
 }
diff --git a/src/platforms/native/bridge/INativeBridge.ts b/src/platforms/native/bridge/INativeBridge.ts
index 7a62ccdf..2ef053e5 100644
--- a/src/platforms/native/bridge/INativeBridge.ts
+++ b/src/platforms/native/bridge/INativeBridge.ts
@@ -183,4 +183,23 @@ export interface INativeBridge {
     parameters?: Record<string, any>,
     headers?: Record<string, string>
   ): Promise<SessionTransferCredentials>;
+
+  /**
+   * Performs a Custom Token Exchange, exchanging an external provider's token
+   * for Auth0 credentials using RFC 8693 Token Exchange.
+   *
+   * @param subjectToken The external token to exchange.
+   * @param subjectTokenType The type identifier of the external token (URI).
+   * @param audience Optional target API identifier.
+   * @param scope Optional space-separated scopes.
+   * @param organization Optional organization ID or name.
+   * @returns A promise that resolves with Auth0 credentials.
+   */
+  customTokenExchange(
+    subjectToken: string,
+    subjectTokenType: string,
+    audience?: string,
+    scope?: string,
+    organization?: string
+  ): Promise<Credentials>;
 }
diff --git a/src/platforms/native/bridge/NativeBridgeManager.ts b/src/platforms/native/bridge/NativeBridgeManager.ts
index a1e36643..bb61a981 100644
--- a/src/platforms/native/bridge/NativeBridgeManager.ts
+++ b/src/platforms/native/bridge/NativeBridgeManager.ts
@@ -222,4 +222,22 @@ export class NativeBridgeManager implements INativeBridge {
       hdrs
     );
   }
+
+  async customTokenExchange(
+    subjectToken: string,
+    subjectTokenType: string,
+    audience?: string,
+    scope?: string,
+    organization?: string
+  ): Promise<Credentials> {
+    const credential = await this.a0_call(
+      Auth0NativeModule.customTokenExchange.bind(Auth0NativeModule),
+      subjectToken,
+      subjectTokenType,
+      audience,
+      scope,
+      organization
+    );
+    return new CredentialsModel(credential);
+  }
 }
diff --git a/src/platforms/web/adapters/WebAuth0Client.ts b/src/platforms/web/adapters/WebAuth0Client.ts
index 394b3fbc..6ab2b4a2 100644
--- a/src/platforms/web/adapters/WebAuth0Client.ts
+++ b/src/platforms/web/adapters/WebAuth0Client.ts
@@ -3,9 +3,17 @@ import {
   type Auth0ClientOptions,
   type LogoutOptions,
 } from '@auth0/auth0-spa-js';
-import type { IAuth0Client, IUsersClient } from '../../../core/interfaces';
+import type {
+  IAuth0Client,
+  IAuthenticationProvider,
+  IUsersClient,
+} from '../../../core/interfaces';
 import type { WebAuth0Options } from '../../../types/platform-specific';
-import type { DPoPHeadersParams } from '../../../types';
+import type {
+  DPoPHeadersParams,
+  CustomTokenExchangeParameters,
+  Credentials,
+} from '../../../types';
 import { WebWebAuthProvider } from './WebWebAuthProvider';
 import { WebCredentialsManager } from './WebCredentialsManager';
 import {
@@ -19,7 +27,7 @@ import { AuthError, DPoPError } from '../../../core/models';
 export class WebAuth0Client implements IAuth0Client {
   readonly webAuth: WebWebAuthProvider;
   readonly credentialsManager: WebCredentialsManager;
-  readonly auth: AuthenticationOrchestrator;
+  readonly auth: IAuthenticationProvider;
 
   private readonly httpClient: HttpClient;
   private readonly tokenType: TokenType;
@@ -198,4 +206,38 @@ export class WebAuth0Client implements IAuth0Client {
       throw new DPoPError(authError);
     }
   }
+
+  /**
+   * Performs a Custom Token Exchange using RFC 8693.
+   * Exchanges an external identity provider token for Auth0 tokens.
+   *
+   * @param parameters The token exchange parameters.
+   * @returns A promise that resolves with Auth0 credentials.
+   */
+  async customTokenExchange(
+    parameters: CustomTokenExchangeParameters
+  ): Promise<Credentials> {
+    const { subjectToken, subjectTokenType, audience, scope, organization } =
+      parameters;
+
+    const response = await this.client.exchangeToken({
+      subject_token: subjectToken,
+      subject_token_type: subjectTokenType,
+      audience,
+      scope,
+      organization,
+    });
+
+    // Convert expiresIn (seconds from now) to expiresAt (UNIX timestamp)
+    const expiresAt = Math.floor(Date.now() / 1000) + response.expires_in;
+
+    return {
+      accessToken: response.access_token,
+      idToken: response.id_token,
+      tokenType: (response.token_type as TokenType) ?? this.tokenType,
+      expiresAt,
+      scope: response.scope,
+      refreshToken: response.refresh_token,
+    };
+  }
 }
diff --git a/src/specs/NativeA0Auth0.ts b/src/specs/NativeA0Auth0.ts
index 36c18272..280bad92 100644
--- a/src/specs/NativeA0Auth0.ts
+++ b/src/specs/NativeA0Auth0.ts
@@ -144,6 +144,18 @@ export interface Spec extends TurboModule {
     idToken?: string;
     refreshToken?: string;
   }>;
+
+  /**
+   * Perform Custom Token Exchange (RFC 8693)
+   * Exchanges an external token for Auth0 tokens.
+   */
+  customTokenExchange(
+    subjectToken: string,
+    subjectTokenType: string,
+    audience: string | undefined,
+    scope: string | undefined,
+    organization: string | undefined
+  ): Promise<Credentials>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('A0Auth0');
diff --git a/src/types/parameters.ts b/src/types/parameters.ts
index 05a35956..63262b0b 100644
--- a/src/types/parameters.ts
+++ b/src/types/parameters.ts
@@ -114,6 +114,55 @@ export interface ExchangeNativeSocialParameters extends RequestOptions {
   scope?: string;
 }
 
+/**
+ * Parameters for Custom Token Exchange (RFC 8693).
+ * Exchanges an external identity provider token for Auth0 tokens.
+ *
+ * Custom Token Exchange allows you to exchange tokens from external identity
+ * providers for Auth0 tokens. The external token must be validated in Auth0
+ * Actions using cryptographic verification.
+ *
+ * @see https://auth0.com/docs/authenticate/login/custom-token-exchange
+ */
+export interface CustomTokenExchangeParameters {
+  /**
+   * The external token to be exchanged for Auth0 tokens.
+   * Must be validated in Auth0 Actions using cryptographic verification.
+   */
+  subjectToken: string;
+
+  /**
+   * The type identifier for the subject token being exchanged.
+   * Must be a namespaced URI under your organization's control.
+   *
+   * Forbidden patterns:
+   * - `urn:ietf:params:oauth:*` (IETF reserved)
+   * - `https://auth0.com/*` (Auth0 reserved)
+   * - `urn:auth0:*` (Auth0 reserved)
+   *
+   * @example "urn:acme:legacy-system-token"
+   */
+  subjectTokenType: string;
+
+  /**
+   * The target audience for the requested Auth0 token.
+   * Must match an API identifier configured in your Auth0 tenant.
+   */
+  audience?: string;
+
+  /**
+   * Space-separated list of OAuth 2.0 scopes.
+   * @default "openid profile email"
+   */
+  scope?: string;
+
+  /**
+   * Organization ID or name for authenticating in an organization context.
+   * When provided, the organization ID will be present in the access token.
+   */
+  organization?: string;
+}
+
 /**
  * Parameters for authenticating with a username and password.
  * @see https://auth0.com/docs/api-auth/grant/password

From 3192a3fe79d74885841b74b0df0b36e4ba69463f Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Tue, 13 Jan 2026 10:58:54 +0530
Subject: [PATCH 2/8] test: add unit tests for customTokenExchange
 functionality across platforms

---
 src/hooks/__tests__/Auth0Provider.spec.tsx    | 226 ++++++++++++++++++
 .../__tests__/NativeAuth0Client.spec.ts       | 109 +++++++++
 .../__tests__/NativeBridgeManager.spec.ts     | 115 ++++++++-
 .../adapters/__tests__/WebAuth0Client.spec.ts | 111 +++++++++
 4 files changed, 559 insertions(+), 2 deletions(-)

diff --git a/src/hooks/__tests__/Auth0Provider.spec.tsx b/src/hooks/__tests__/Auth0Provider.spec.tsx
index 31c60f39..4b6a6cca 100644
--- a/src/hooks/__tests__/Auth0Provider.spec.tsx
+++ b/src/hooks/__tests__/Auth0Provider.spec.tsx
@@ -1053,6 +1053,232 @@ describe('Auth0Provider', () => {
     });
   });
 
+  // Custom Token Exchange Tests
+  describe('customTokenExchange', () => {
+    const mockExchangeCredentials = {
+      idToken: 'exchanged.id.token',
+      accessToken: 'exchanged-access-token',
+      tokenType: 'Bearer',
+      expiresAt: Date.now() / 1000 + 3600,
+      scope: 'openid profile email',
+      refreshToken: 'exchanged-refresh-token',
+    };
+
+    const TestCustomTokenExchangeConsumer = () => {
+      const { customTokenExchange, user, error, isLoading } = useAuth0();
+
+      const handleExchange = () => {
+        customTokenExchange({
+          subjectToken: 'external-token',
+          subjectTokenType: 'urn:acme:legacy-token',
+          audience: 'https://api.example.com',
+          scope: 'openid profile email',
+          organization: 'org_123',
+        }).catch(() => {});
+      };
+
+      if (isLoading) return <Text testID="loading">Loading...</Text>;
+      if (error) return <Text testID="error">Error: {error.message}</Text>;
+
+      return (
+        <View>
+          {user ? (
+            <Text testID="user-status">Logged in as: {user.name}</Text>
+          ) : (
+            <Text testID="user-status">Not logged in</Text>
+          )}
+          <Button
+            title="Exchange Token"
+            onPress={handleExchange}
+            testID="exchange-button"
+          />
+        </View>
+      );
+    };
+
+    beforeEach(() => {
+      mockClientInstance.customTokenExchange = jest
+        .fn()
+        .mockResolvedValue(mockExchangeCredentials);
+    });
+
+    it('should call customTokenExchange with all parameters', async () => {
+      await act(async () => {
+        render(
+          <Auth0Provider domain="test.com" clientId="123">
+            <TestCustomTokenExchangeConsumer />
+          </Auth0Provider>
+        );
+      });
+
+      await waitFor(() =>
+        expect(screen.getByTestId('user-status')).toHaveTextContent(
+          'Not logged in'
+        )
+      );
+
+      const exchangeButton = screen.getByTestId('exchange-button');
+      await act(async () => {
+        fireEvent.click(exchangeButton);
+      });
+
+      expect(mockClientInstance.customTokenExchange).toHaveBeenCalledWith({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+        audience: 'https://api.example.com',
+        scope: 'openid profile email',
+        organization: 'org_123',
+      });
+    });
+
+    it('should update user state after successful token exchange', async () => {
+      await act(async () => {
+        render(
+          <Auth0Provider domain="test.com" clientId="123">
+            <TestCustomTokenExchangeConsumer />
+          </Auth0Provider>
+        );
+      });
+
+      await waitFor(() =>
+        expect(screen.getByTestId('user-status')).toHaveTextContent(
+          'Not logged in'
+        )
+      );
+
+      const exchangeButton = screen.getByTestId('exchange-button');
+      await act(async () => {
+        fireEvent.click(exchangeButton);
+      });
+
+      await waitFor(() =>
+        expect(screen.getByTestId('user-status')).toHaveTextContent(
+          'Logged in as: Test User'
+        )
+      );
+
+      // Should save credentials after exchange
+      expect(
+        mockClientInstance.credentialsManager.saveCredentials
+      ).toHaveBeenCalledWith(mockExchangeCredentials);
+    });
+
+    it('should handle customTokenExchange error and dispatch to state', async () => {
+      const exchangeError = new Error('Token exchange failed');
+      mockClientInstance.customTokenExchange.mockRejectedValueOnce(
+        exchangeError
+      );
+
+      await act(async () => {
+        render(
+          <Auth0Provider domain="test.com" clientId="123">
+            <TestCustomTokenExchangeConsumer />
+          </Auth0Provider>
+        );
+      });
+
+      await waitFor(() =>
+        expect(screen.getByTestId('user-status')).toHaveTextContent(
+          'Not logged in'
+        )
+      );
+
+      const exchangeButton = screen.getByTestId('exchange-button');
+      await act(async () => {
+        fireEvent.click(exchangeButton);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('error')).toHaveTextContent(
+          'Error: Token exchange failed'
+        );
+      });
+    });
+
+    it('should call customTokenExchange with minimal parameters', async () => {
+      const TestMinimalExchangeConsumer = () => {
+        const { customTokenExchange } = useAuth0();
+
+        const handleMinimalExchange = () => {
+          customTokenExchange({
+            subjectToken: 'external-token',
+            subjectTokenType: 'urn:acme:legacy-token',
+          }).catch(() => {});
+        };
+
+        return (
+          <Button
+            title="Minimal Exchange"
+            onPress={handleMinimalExchange}
+            testID="minimal-exchange-button"
+          />
+        );
+      };
+
+      await act(async () => {
+        render(
+          <Auth0Provider domain="test.com" clientId="123">
+            <TestMinimalExchangeConsumer />
+          </Auth0Provider>
+        );
+      });
+
+      const exchangeButton = screen.getByTestId('minimal-exchange-button');
+      await act(async () => {
+        fireEvent.click(exchangeButton);
+      });
+
+      expect(mockClientInstance.customTokenExchange).toHaveBeenCalledWith({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      });
+    });
+
+    it('should return credentials from customTokenExchange', async () => {
+      let returnedCredentials: any = null;
+
+      const TestReturnValueConsumer = () => {
+        const { customTokenExchange } = useAuth0();
+
+        const handleExchange = async () => {
+          try {
+            returnedCredentials = await customTokenExchange({
+              subjectToken: 'external-token',
+              subjectTokenType: 'urn:acme:legacy-token',
+            });
+          } catch {
+            // ignore
+          }
+        };
+
+        return (
+          <Button
+            title="Exchange"
+            onPress={handleExchange}
+            testID="return-value-exchange-button"
+          />
+        );
+      };
+
+      await act(async () => {
+        render(
+          <Auth0Provider domain="test.com" clientId="123">
+            <TestReturnValueConsumer />
+          </Auth0Provider>
+        );
+      });
+
+      const exchangeButton = screen.getByTestId('return-value-exchange-button');
+      await act(async () => {
+        fireEvent.click(exchangeButton);
+      });
+
+      await waitFor(() => {
+        expect(returnedCredentials).toEqual(mockExchangeCredentials);
+      });
+    });
+  });
+
   // Web Platform Method Tests
   describe('Web Platform Methods', () => {
     it('should verify webAuth methods exist and are callable', () => {
diff --git a/src/platforms/native/adapters/__tests__/NativeAuth0Client.spec.ts b/src/platforms/native/adapters/__tests__/NativeAuth0Client.spec.ts
index 6b831c5c..d2b1cccd 100644
--- a/src/platforms/native/adapters/__tests__/NativeAuth0Client.spec.ts
+++ b/src/platforms/native/adapters/__tests__/NativeAuth0Client.spec.ts
@@ -166,4 +166,113 @@ describe('NativeAuth0Client', () => {
     await authorizePromise;
     expect(mockBridgeInstance.authorize).toHaveBeenCalledTimes(1);
   });
+
+  describe('customTokenExchange', () => {
+    const mockCredentials = {
+      idToken: 'mock-id-token',
+      accessToken: 'mock-access-token',
+      tokenType: 'Bearer',
+      expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      refreshToken: 'mock-refresh-token',
+      scope: 'openid profile email',
+    };
+
+    beforeEach(() => {
+      // Add customTokenExchange to the mock methods
+      (mockBridgeInstance as any).customTokenExchange = jest
+        .fn()
+        .mockResolvedValue(mockCredentials);
+    });
+
+    it('should call customTokenExchange on the guarded bridge with all parameters', async () => {
+      const client = new NativeAuth0Client(options);
+      await new Promise(process.nextTick);
+
+      const parameters = {
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+        audience: 'https://api.example.com',
+        scope: 'openid profile email',
+        organization: 'org_123',
+      };
+
+      await client.customTokenExchange(parameters);
+
+      expect(
+        (mockBridgeInstance as any).customTokenExchange
+      ).toHaveBeenCalledWith(
+        'external-token',
+        'urn:acme:legacy-token',
+        'https://api.example.com',
+        'openid profile email',
+        'org_123'
+      );
+    });
+
+    it('should call customTokenExchange with only required parameters', async () => {
+      const client = new NativeAuth0Client(options);
+      await new Promise(process.nextTick);
+
+      const parameters = {
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      };
+
+      await client.customTokenExchange(parameters);
+
+      expect(
+        (mockBridgeInstance as any).customTokenExchange
+      ).toHaveBeenCalledWith(
+        'external-token',
+        'urn:acme:legacy-token',
+        undefined,
+        undefined,
+        undefined
+      );
+    });
+
+    it('should return credentials from customTokenExchange', async () => {
+      const client = new NativeAuth0Client(options);
+      await new Promise(process.nextTick);
+
+      const result = await client.customTokenExchange({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      });
+
+      expect(result).toEqual(mockCredentials);
+    });
+
+    it('should wait for initialization before calling customTokenExchange', async () => {
+      let resolveInitialization: () => void;
+      const initializationPromise = new Promise<void>((resolve) => {
+        resolveInitialization = resolve;
+      });
+
+      mockBridgeInstance.initialize.mockReturnValue(initializationPromise);
+      mockBridgeInstance.hasValidInstance.mockResolvedValue(false);
+
+      const client = new NativeAuth0Client(options);
+
+      const exchangePromise = client.customTokenExchange({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      });
+
+      // Should not be called yet since initialization is pending
+      expect(
+        (mockBridgeInstance as any).customTokenExchange
+      ).not.toHaveBeenCalled();
+
+      // Resolve initialization
+      await act(async () => {
+        resolveInitialization!();
+      });
+
+      await exchangePromise;
+      expect(
+        (mockBridgeInstance as any).customTokenExchange
+      ).toHaveBeenCalledTimes(1);
+    });
+  });
 });
diff --git a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
index 909290ec..43717362 100644
--- a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
+++ b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
@@ -3,7 +3,25 @@ import { AuthError, Credentials } from '../../../../core/models';
 import Auth0NativeModule from '../../../../specs/NativeA0Auth0';
 
 // Mock the entire spec file, which is our native module.
-jest.mock('../../../../specs/NativeA0Auth0');
+jest.mock('../../../../specs/NativeA0Auth0', () => ({
+  webAuth: jest.fn(),
+  webAuthLogout: jest.fn(),
+  getCredentials: jest.fn(),
+  hasValidAuth0InstanceWithConfiguration: jest.fn(),
+  initializeAuth0WithConfiguration: jest.fn(),
+  getBundleIdentifier: jest.fn(),
+  saveCredentials: jest.fn(),
+  hasValidCredentials: jest.fn(),
+  clearCredentials: jest.fn(),
+  cancelWebAuth: jest.fn(),
+  resumeWebAuth: jest.fn(),
+  getDPoPHeaders: jest.fn(),
+  clearDPoPKey: jest.fn(),
+  getSSOCredentials: jest.fn(),
+  customTokenExchange: jest.fn(),
+  getApiCredentials: jest.fn(),
+  clearApiCredentials: jest.fn(),
+}));
 const MockedAuth0NativeModule = Auth0NativeModule as jest.Mocked<
   typeof Auth0NativeModule
 >;
@@ -159,7 +177,7 @@ describe('NativeBridgeManager', () => {
         code: 'a0.session.user_cancelled',
         message: 'User cancelled the Auth',
       };
-      MockedAuth0NativeModule.webAuth.mockRejectedValueOnce(nativeError);
+      MockedAuth0NativeModule.webAuth.mockRejectedValue(nativeError);
 
       await expect(bridge.authorize({} as any, {} as any)).rejects.toThrow(
         AuthError
@@ -175,4 +193,97 @@ describe('NativeBridgeManager', () => {
       }
     });
   });
+
+  describe('customTokenExchange', () => {
+    const mockExchangeResponse = {
+      idToken: validIdToken,
+      accessToken: 'exchanged-access-token',
+      tokenType: 'Bearer',
+      expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      refreshToken: 'exchanged-refresh-token',
+      scope: 'openid profile email',
+    };
+
+    it('should call the native customTokenExchange method with all parameters', async () => {
+      MockedAuth0NativeModule.customTokenExchange.mockResolvedValueOnce(
+        mockExchangeResponse as any
+      );
+
+      await bridge.customTokenExchange(
+        'external-token',
+        'urn:acme:legacy-token',
+        'https://api.example.com',
+        'openid profile email',
+        'org_123'
+      );
+
+      expect(MockedAuth0NativeModule.customTokenExchange).toHaveBeenCalledTimes(
+        1
+      );
+      expect(MockedAuth0NativeModule.customTokenExchange).toHaveBeenCalledWith(
+        'external-token',
+        'urn:acme:legacy-token',
+        'https://api.example.com',
+        'openid profile email',
+        'org_123'
+      );
+    });
+
+    it('should call native method with undefined for optional parameters', async () => {
+      MockedAuth0NativeModule.customTokenExchange.mockResolvedValueOnce(
+        mockExchangeResponse as any
+      );
+
+      await bridge.customTokenExchange(
+        'external-token',
+        'urn:acme:legacy-token'
+      );
+
+      expect(MockedAuth0NativeModule.customTokenExchange).toHaveBeenCalledWith(
+        'external-token',
+        'urn:acme:legacy-token',
+        undefined,
+        undefined,
+        undefined
+      );
+    });
+
+    it('should correctly transform the native response to a Credentials model', async () => {
+      MockedAuth0NativeModule.customTokenExchange.mockResolvedValueOnce(
+        mockExchangeResponse as any
+      );
+
+      const credentials = await bridge.customTokenExchange(
+        'external-token',
+        'urn:acme:legacy-token'
+      );
+
+      expect(credentials).toBeInstanceOf(Credentials);
+      expect(credentials.accessToken).toBe('exchanged-access-token');
+      expect(credentials.idToken).toBe(validIdToken);
+      expect(credentials.tokenType).toBe('Bearer');
+    });
+
+    it('should throw AuthError when native method fails', async () => {
+      const nativeError = {
+        code: 'a0.token_exchange_failed',
+        message: 'Token exchange failed',
+      };
+      MockedAuth0NativeModule.customTokenExchange.mockRejectedValue(
+        nativeError
+      );
+
+      await expect(
+        bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token')
+      ).rejects.toThrow(AuthError);
+
+      try {
+        await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
+      } catch (e) {
+        const authError = e as AuthError;
+        expect(authError.code).toBe('a0.token_exchange_failed');
+        expect(authError.message).toBe('Token exchange failed');
+      }
+    });
+  });
 });
diff --git a/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts b/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
index 8c9088e6..3b6ffd9f 100644
--- a/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
+++ b/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
@@ -309,4 +309,115 @@ describe('WebAuth0Client', () => {
       expect(MockWebCredentialsManager).toHaveBeenCalledWith(mockSpaClient);
     });
   });
+
+  describe('customTokenExchange method', () => {
+    const mockExchangeResponse = {
+      access_token: 'exchanged-access-token',
+      id_token: 'exchanged-id-token',
+      token_type: 'Bearer',
+      expires_in: 3600,
+      scope: 'openid profile email',
+      refresh_token: 'exchanged-refresh-token',
+    };
+
+    beforeEach(() => {
+      mockSpaClient.exchangeToken = jest
+        .fn()
+        .mockResolvedValue(mockExchangeResponse);
+    });
+
+    it('should call exchangeToken on SPA client with all parameters', async () => {
+      const parameters = {
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+        audience: 'https://api.example.com',
+        scope: 'openid profile email',
+        organization: 'org_123',
+      };
+
+      await client.customTokenExchange(parameters);
+
+      expect(mockSpaClient.exchangeToken).toHaveBeenCalledWith({
+        subject_token: 'external-token',
+        subject_token_type: 'urn:acme:legacy-token',
+        audience: 'https://api.example.com',
+        scope: 'openid profile email',
+        organization: 'org_123',
+      });
+    });
+
+    it('should call exchangeToken with only required parameters', async () => {
+      const parameters = {
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      };
+
+      await client.customTokenExchange(parameters);
+
+      expect(mockSpaClient.exchangeToken).toHaveBeenCalledWith({
+        subject_token: 'external-token',
+        subject_token_type: 'urn:acme:legacy-token',
+        audience: undefined,
+        scope: undefined,
+        organization: undefined,
+      });
+    });
+
+    it('should return credentials with correct structure', async () => {
+      const result = await client.customTokenExchange({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      });
+
+      expect(result.accessToken).toBe('exchanged-access-token');
+      expect(result.idToken).toBe('exchanged-id-token');
+      expect(result.tokenType).toBe('Bearer');
+      expect(result.scope).toBe('openid profile email');
+      expect(result.refreshToken).toBe('exchanged-refresh-token');
+      // expiresAt should be a timestamp in the future
+      expect(result.expiresAt).toBeGreaterThan(Math.floor(Date.now() / 1000));
+    });
+
+    it('should convert expires_in to expiresAt timestamp', async () => {
+      const beforeCall = Math.floor(Date.now() / 1000);
+
+      const result = await client.customTokenExchange({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      });
+
+      const afterCall = Math.floor(Date.now() / 1000);
+
+      // expiresAt should be approximately now + expires_in (3600 seconds)
+      expect(result.expiresAt).toBeGreaterThanOrEqual(beforeCall + 3600);
+      expect(result.expiresAt).toBeLessThanOrEqual(afterCall + 3600);
+    });
+
+    it('should use client tokenType as fallback when response token_type is missing', async () => {
+      mockSpaClient.exchangeToken.mockResolvedValueOnce({
+        ...mockExchangeResponse,
+        token_type: undefined,
+      });
+
+      const result = await client.customTokenExchange({
+        subjectToken: 'external-token',
+        subjectTokenType: 'urn:acme:legacy-token',
+      });
+
+      // Should use client's default tokenType (DPoP)
+      expect(result.tokenType).toBe('DPoP');
+    });
+
+    it('should propagate errors from exchangeToken', async () => {
+      const exchangeError = new Error('Token exchange failed');
+      mockSpaClient.exchangeToken.mockRejectedValueOnce(exchangeError);
+
+      await expect(
+        client.customTokenExchange({
+          subjectToken: 'bad-token',
+          subjectTokenType: 'urn:acme:legacy-token',
+        })
+      ).rejects.toThrow('Token exchange failed');
+    });
+  });
 });

From 80c600d7135782e690549f7209bca8d61d6e1b0e Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Tue, 13 Jan 2026 11:11:05 +0530
Subject: [PATCH 3/8] feat: implement Custom Token Exchange error handling and
 documentation

---
 EXAMPLES.md                                   |  74 +++++-
 src/core/models/CustomTokenExchangeError.ts   | 213 +++++++++++++++++
 .../CustomTokenExchangeError.spec.ts          | 217 ++++++++++++++++++
 src/core/models/index.ts                      |   4 +
 src/index.ts                                  |   2 +
 .../native/bridge/NativeBridgeManager.ts      |  27 ++-
 .../__tests__/NativeBridgeManager.spec.ts     |  53 ++++-
 src/platforms/web/adapters/WebAuth0Client.ts  |  55 +++--
 .../adapters/__tests__/WebAuth0Client.spec.ts |  81 ++++++-
 9 files changed, 676 insertions(+), 50 deletions(-)
 create mode 100644 src/core/models/CustomTokenExchangeError.ts
 create mode 100644 src/core/models/__tests__/CustomTokenExchangeError.spec.ts

diff --git a/EXAMPLES.md b/EXAMPLES.md
index d663f413..729a2baf 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -579,7 +579,11 @@ Custom Token Exchange allows you to exchange external identity provider tokens f
 ```typescript
 import React from 'react';
 import { Button, Alert } from 'react-native';
-import { useAuth0 } from 'react-native-auth0';
+import {
+  useAuth0,
+  CustomTokenExchangeError,
+  CustomTokenExchangeErrorCodes,
+} from 'react-native-auth0';
 
 function TokenExchangeScreen() {
   const { customTokenExchange, user, error } = useAuth0();
@@ -596,7 +600,32 @@ function TokenExchangeScreen() {
 
       Alert.alert('Success', `Logged in as ${user?.name}`);
     } catch (e) {
-      console.error('Token exchange failed:', e);
+      if (e instanceof CustomTokenExchangeError) {
+        switch (e.type) {
+          case CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN:
+            Alert.alert('Error', 'The external token is invalid or expired');
+            break;
+          case CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE:
+            Alert.alert('Error', 'The token type is not supported');
+            break;
+          case CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED:
+            Alert.alert(
+              'Error',
+              'Custom Token Exchange is not configured for this tenant'
+            );
+            break;
+          case CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED:
+            Alert.alert('Error', 'Token validation failed in Auth0 Action');
+            break;
+          case CustomTokenExchangeErrorCodes.NETWORK_ERROR:
+            Alert.alert('Error', 'Network error. Please check your connection.');
+            break;
+          default:
+            Alert.alert('Error', e.message);
+        }
+      } else {
+        console.error('Token exchange failed:', e);
+      }
     }
   };
 
@@ -607,7 +636,10 @@ function TokenExchangeScreen() {
 ### Using Custom Token Exchange with Auth0 Class
 
 ```typescript
-import Auth0 from 'react-native-auth0';
+import Auth0, {
+  CustomTokenExchangeError,
+  CustomTokenExchangeErrorCodes,
+} from 'react-native-auth0';
 
 const auth0 = new Auth0({
   domain: 'YOUR_AUTH0_DOMAIN',
@@ -626,7 +658,18 @@ async function exchangeExternalToken(externalToken: string) {
     console.log('Exchange successful:', credentials);
     return credentials;
   } catch (error) {
-    console.error('Exchange failed:', error);
+    if (error instanceof CustomTokenExchangeError) {
+      // Access the underlying error details
+      console.error('Error type:', error.type);
+      console.error('Error message:', error.message);
+      console.error('Underlying error code:', error.underlyingError.code);
+
+      // Handle specific error types
+      if (error.type === CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN) {
+        // Token is invalid or expired - prompt user to re-authenticate
+        throw new Error('Please authenticate again with the external provider');
+      }
+    }
     throw error;
   }
 }
@@ -658,6 +701,29 @@ Valid examples:
 - `urn:acme:legacy-system-token`
 - `https://yourcompany.com/tokens/legacy`
 
+### Error Codes Reference
+
+The `CustomTokenExchangeError` class provides platform-agnostic error codes that are mapped from the underlying native SDK errors. Use the `type` property for programmatic error handling:
+
+| Error Code                      | Description                                                |
+| ------------------------------- | ---------------------------------------------------------- |
+| `INVALID_SUBJECT_TOKEN`         | The external token is invalid, malformed, or expired       |
+| `UNSUPPORTED_TOKEN_TYPE`        | The token type is not supported or recognized              |
+| `TOKEN_EXCHANGE_NOT_CONFIGURED` | Custom Token Exchange is not enabled for this Auth0 tenant |
+| `INVALID_AUDIENCE`              | The requested audience is invalid or not allowed           |
+| `INVALID_SCOPE`                 | The requested scope is invalid or not allowed              |
+| `TOKEN_EXCHANGE_DENIED`         | Token exchange was denied by the authorization server      |
+| `TOKEN_VALIDATION_FAILED`       | The token validation in Auth0 Action failed                |
+| `NETWORK_ERROR`                 | Network connectivity issue occurred                        |
+| `SERVER_ERROR`                  | The authorization server encountered an internal error     |
+| `UNKNOWN_ERROR`                 | An unknown or uncategorized error occurred                 |
+
+These error codes are mapped from:
+
+- **RFC 8693 standard errors**: `invalid_grant`, `invalid_request`, `unsupported_token_type`, `access_denied`, etc.
+- **Auth0-specific errors**: `a0.token_exchange_failed`, `a0.action_failed`, etc.
+- **Native SDK errors**: Platform-specific error codes from Auth0.swift and Auth0.Android
+
 ## Native to Web SSO (Early Access)
 
 > ⚠️ **Early Access Feature**: Native to Web SSO is currently available in Early Access. To use this feature, you must have an Enterprise plan. For more information, see [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
diff --git a/src/core/models/CustomTokenExchangeError.ts b/src/core/models/CustomTokenExchangeError.ts
new file mode 100644
index 00000000..e25b935d
--- /dev/null
+++ b/src/core/models/CustomTokenExchangeError.ts
@@ -0,0 +1,213 @@
+import { AuthError } from './AuthError';
+
+/**
+ * Platform-agnostic error code constants for Custom Token Exchange operations.
+ *
+ * Use these constants for type-safe error handling when working with token exchange.
+ * Each constant corresponds to a specific error type in the {@link CustomTokenExchangeError.type} property.
+ *
+ * @example
+ * ```typescript
+ * import { CustomTokenExchangeError, CustomTokenExchangeErrorCodes } from 'react-native-auth0';
+ *
+ * try {
+ *   const credentials = await auth0.customTokenExchange({
+ *     subjectToken: externalToken,
+ *     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof CustomTokenExchangeError) {
+ *     switch (e.type) {
+ *       case CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN:
+ *         // The external token is invalid or expired
+ *         break;
+ *       case CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE:
+ *         // The token type is not supported
+ *         break;
+ *       case CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED:
+ *         // Custom Token Exchange is not configured in Auth0
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link CustomTokenExchangeError}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
+ */
+export const CustomTokenExchangeErrorCodes = {
+  /** The subject token is invalid, malformed, or expired */
+  INVALID_SUBJECT_TOKEN: 'INVALID_SUBJECT_TOKEN',
+  /** The subject token type is not supported or not recognized */
+  UNSUPPORTED_TOKEN_TYPE: 'UNSUPPORTED_TOKEN_TYPE',
+  /** Custom Token Exchange is not configured or enabled for this Auth0 tenant */
+  TOKEN_EXCHANGE_NOT_CONFIGURED: 'TOKEN_EXCHANGE_NOT_CONFIGURED',
+  /** The requested audience is invalid or not allowed */
+  INVALID_AUDIENCE: 'INVALID_AUDIENCE',
+  /** The requested scope is invalid or not allowed */
+  INVALID_SCOPE: 'INVALID_SCOPE',
+  /** Token exchange was denied by the authorization server */
+  TOKEN_EXCHANGE_DENIED: 'TOKEN_EXCHANGE_DENIED',
+  /** The token validation in Auth0 Action failed */
+  TOKEN_VALIDATION_FAILED: 'TOKEN_VALIDATION_FAILED',
+  /** Network error occurred during token exchange */
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  /** The authorization server encountered an internal error */
+  SERVER_ERROR: 'SERVER_ERROR',
+  /** Unknown or uncategorized token exchange error */
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+} as const;
+
+/**
+ * Type for the values of CustomTokenExchangeErrorCodes.
+ */
+export type CustomTokenExchangeErrorCode =
+  (typeof CustomTokenExchangeErrorCodes)[keyof typeof CustomTokenExchangeErrorCodes];
+
+const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
+  // --- RFC 8693 OAuth 2.0 Token Exchange error codes ---
+  'invalid_request': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+  'invalid_grant': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+  'invalid_token': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+  'unsupported_token_type':
+    CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
+  'invalid_target': CustomTokenExchangeErrorCodes.INVALID_AUDIENCE,
+  'invalid_scope': CustomTokenExchangeErrorCodes.INVALID_SCOPE,
+  'access_denied': CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
+  'unauthorized_client':
+    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+  'server_error': CustomTokenExchangeErrorCodes.SERVER_ERROR,
+
+  // --- Auth0-specific error codes ---
+  'a0.token_exchange_failed':
+    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
+  'a0.token_exchange_not_enabled':
+    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+  'a0.invalid_subject_token':
+    CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+  'a0.subject_token_expired':
+    CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+  'a0.subject_token_validation_failed':
+    CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
+  'a0.action_failed': CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
+
+  // --- Native SDK codes (iOS/Android) ---
+  'INVALID_SUBJECT_TOKEN': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+  'UNSUPPORTED_TOKEN_TYPE':
+    CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
+  'TOKEN_EXCHANGE_FAILED': CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
+  'TOKEN_EXCHANGE_NOT_CONFIGURED':
+    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+  'TOKEN_VALIDATION_FAILED':
+    CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
+
+  // --- Network errors ---
+  'a0.network_error': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
+  'NETWORK_ERROR': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
+  'network_error': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
+};
+
+/**
+ * Represents an error that occurred during Custom Token Exchange (RFC 8693).
+ *
+ * This error class provides structured error handling for token exchange operations,
+ * with platform-agnostic error codes that normalize errors from iOS, Android, and web platforms.
+ *
+ * Custom Token Exchange allows exchanging external identity provider tokens for Auth0 tokens.
+ * Common failure scenarios include:
+ * - Invalid or expired external tokens
+ * - Unsupported token types
+ * - Missing or misconfigured Auth0 Actions for token validation
+ * - Network connectivity issues
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   CustomTokenExchangeError,
+ *   CustomTokenExchangeErrorCodes
+ * } from 'react-native-auth0';
+ *
+ * try {
+ *   const credentials = await auth0.customTokenExchange({
+ *     subjectToken: externalToken,
+ *     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
+ *     audience: 'https://api.example.com',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof CustomTokenExchangeError) {
+ *     console.log('Error type:', e.type);
+ *     console.log('Error message:', e.message);
+ *
+ *     if (e.type === CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED) {
+ *       // Prompt user or admin to configure Custom Token Exchange
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link CustomTokenExchangeErrorCodes}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
+ * @see {@link https://auth0.com/docs/authenticate/login/custom-token-exchange|Auth0 Custom Token Exchange}
+ */
+export class CustomTokenExchangeError extends Error {
+  /**
+   * The platform-agnostic error type. Use this for switch statements and error handling.
+   */
+  public readonly type: CustomTokenExchangeErrorCode;
+
+  /**
+   * The underlying raw error that caused this CustomTokenExchangeError.
+   */
+  public readonly underlyingError: AuthError;
+
+  /**
+   * Creates a new CustomTokenExchangeError.
+   *
+   * Typically you won't need to construct this directly - the SDK automatically
+   * wraps native errors in this class when they occur during token exchange operations.
+   *
+   * @param underlyingError The original AuthError from the platform.
+   */
+  constructor(underlyingError: AuthError) {
+    super(underlyingError.message);
+    this.name = 'CustomTokenExchangeError';
+    this.underlyingError = underlyingError;
+
+    // Map the raw error code to a platform-agnostic type
+    const rawCode = underlyingError.code || underlyingError.name;
+    this.type =
+      ERROR_CODE_MAP[rawCode] ?? CustomTokenExchangeErrorCodes.UNKNOWN_ERROR;
+
+    // Capture stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CustomTokenExchangeError);
+    }
+  }
+
+  /**
+   * Factory method to create a CustomTokenExchangeError from a raw error.
+   *
+   * @param error The error to wrap.
+   * @returns A new CustomTokenExchangeError instance.
+   */
+  static from(error: unknown): CustomTokenExchangeError {
+    if (error instanceof CustomTokenExchangeError) {
+      return error;
+    }
+
+    if (error instanceof AuthError) {
+      return new CustomTokenExchangeError(error);
+    }
+
+    // Handle generic errors or unknown error types
+    const authError = new AuthError(
+      'custom_token_exchange_error',
+      error instanceof Error ? error.message : String(error),
+      {
+        code: 'custom_token_exchange_error',
+        json: error,
+      }
+    );
+    return new CustomTokenExchangeError(authError);
+  }
+}
diff --git a/src/core/models/__tests__/CustomTokenExchangeError.spec.ts b/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
new file mode 100644
index 00000000..3d48b2ee
--- /dev/null
+++ b/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
@@ -0,0 +1,217 @@
+import {
+  CustomTokenExchangeError,
+  CustomTokenExchangeErrorCodes,
+} from '../CustomTokenExchangeError';
+import { AuthError } from '../AuthError';
+
+describe('CustomTokenExchangeError', () => {
+  describe('constructor', () => {
+    it('should create error with correct name', () => {
+      const authError = new AuthError('invalid_grant', 'Token expired', {
+        code: 'invalid_grant',
+      });
+      const error = new CustomTokenExchangeError(authError);
+
+      expect(error.name).toBe('CustomTokenExchangeError');
+    });
+
+    it('should preserve the underlying error', () => {
+      const authError = new AuthError('invalid_grant', 'Token expired', {
+        code: 'invalid_grant',
+      });
+      const error = new CustomTokenExchangeError(authError);
+
+      expect(error.underlyingError).toBe(authError);
+    });
+
+    it('should preserve the error message', () => {
+      const authError = new AuthError('invalid_grant', 'Token expired', {
+        code: 'invalid_grant',
+      });
+      const error = new CustomTokenExchangeError(authError);
+
+      expect(error.message).toBe('Token expired');
+    });
+  });
+
+  describe('error code mapping', () => {
+    it.each([
+      // RFC 8693 error codes
+      ['invalid_request', CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN],
+      ['invalid_grant', CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN],
+      ['invalid_token', CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN],
+      [
+        'unsupported_token_type',
+        CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
+      ],
+      ['invalid_target', CustomTokenExchangeErrorCodes.INVALID_AUDIENCE],
+      ['invalid_scope', CustomTokenExchangeErrorCodes.INVALID_SCOPE],
+      ['access_denied', CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED],
+      [
+        'unauthorized_client',
+        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+      ],
+      ['server_error', CustomTokenExchangeErrorCodes.SERVER_ERROR],
+
+      // Auth0-specific error codes
+      [
+        'a0.token_exchange_failed',
+        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
+      ],
+      [
+        'a0.token_exchange_not_enabled',
+        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+      ],
+      [
+        'a0.invalid_subject_token',
+        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+      ],
+      [
+        'a0.subject_token_expired',
+        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+      ],
+      [
+        'a0.subject_token_validation_failed',
+        CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
+      ],
+      [
+        'a0.action_failed',
+        CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
+      ],
+
+      // Native SDK codes
+      [
+        'INVALID_SUBJECT_TOKEN',
+        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
+      ],
+      [
+        'UNSUPPORTED_TOKEN_TYPE',
+        CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
+      ],
+      [
+        'TOKEN_EXCHANGE_FAILED',
+        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
+      ],
+      [
+        'TOKEN_EXCHANGE_NOT_CONFIGURED',
+        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+      ],
+      [
+        'TOKEN_VALIDATION_FAILED',
+        CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
+      ],
+
+      // Network errors
+      ['a0.network_error', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
+      ['NETWORK_ERROR', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
+      ['network_error', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
+    ])('should map "%s" to %s', (errorCode, expectedType) => {
+      const authError = new AuthError(errorCode, 'Test error', {
+        code: errorCode,
+      });
+      const error = new CustomTokenExchangeError(authError);
+
+      expect(error.type).toBe(expectedType);
+    });
+
+    it('should map unknown error codes to UNKNOWN_ERROR', () => {
+      const authError = new AuthError('some_unknown_code', 'Unknown error', {
+        code: 'some_unknown_code',
+      });
+      const error = new CustomTokenExchangeError(authError);
+
+      expect(error.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
+    });
+
+    it('should use default code when code is not explicitly provided', () => {
+      // When code is not provided in details, AuthError defaults to 'unknown_error'
+      const authError = new AuthError('invalid_grant', 'Test error');
+      const error = new CustomTokenExchangeError(authError);
+
+      // Since code defaults to 'unknown_error', it maps to UNKNOWN_ERROR
+      expect(error.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
+    });
+
+    it('should prefer explicit code over name when mapping error type', () => {
+      const authError = new AuthError('some_name', 'Test error', {
+        code: 'invalid_grant',
+      });
+      const error = new CustomTokenExchangeError(authError);
+
+      expect(error.type).toBe(
+        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN
+      );
+    });
+  });
+
+  describe('from factory method', () => {
+    it('should return the same error if already a CustomTokenExchangeError', () => {
+      const authError = new AuthError('invalid_grant', 'Test error');
+      const originalError = new CustomTokenExchangeError(authError);
+      const result = CustomTokenExchangeError.from(originalError);
+
+      expect(result).toBe(originalError);
+    });
+
+    it('should wrap AuthError in CustomTokenExchangeError', () => {
+      const authError = new AuthError('invalid_grant', 'Test error', {
+        code: 'invalid_grant',
+      });
+      const result = CustomTokenExchangeError.from(authError);
+
+      expect(result).toBeInstanceOf(CustomTokenExchangeError);
+      expect(result.underlyingError).toBe(authError);
+    });
+
+    it('should wrap generic Error in CustomTokenExchangeError', () => {
+      const genericError = new Error('Something went wrong');
+      const result = CustomTokenExchangeError.from(genericError);
+
+      expect(result).toBeInstanceOf(CustomTokenExchangeError);
+      expect(result.message).toBe('Something went wrong');
+      expect(result.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
+    });
+
+    it('should wrap string error in CustomTokenExchangeError', () => {
+      const result = CustomTokenExchangeError.from('String error message');
+
+      expect(result).toBeInstanceOf(CustomTokenExchangeError);
+      expect(result.message).toBe('String error message');
+      expect(result.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
+    });
+
+    it('should handle null/undefined errors', () => {
+      const result = CustomTokenExchangeError.from(null);
+
+      expect(result).toBeInstanceOf(CustomTokenExchangeError);
+      expect(result.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
+    });
+  });
+
+  describe('CustomTokenExchangeErrorCodes', () => {
+    it('should export all expected error codes', () => {
+      expect(CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN).toBe(
+        'INVALID_SUBJECT_TOKEN'
+      );
+      expect(CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE).toBe(
+        'UNSUPPORTED_TOKEN_TYPE'
+      );
+      expect(CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED).toBe(
+        'TOKEN_EXCHANGE_NOT_CONFIGURED'
+      );
+      expect(CustomTokenExchangeErrorCodes.INVALID_AUDIENCE).toBe(
+        'INVALID_AUDIENCE'
+      );
+      expect(CustomTokenExchangeErrorCodes.INVALID_SCOPE).toBe('INVALID_SCOPE');
+      expect(CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED).toBe(
+        'TOKEN_EXCHANGE_DENIED'
+      );
+      expect(CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED).toBe(
+        'TOKEN_VALIDATION_FAILED'
+      );
+      expect(CustomTokenExchangeErrorCodes.NETWORK_ERROR).toBe('NETWORK_ERROR');
+      expect(CustomTokenExchangeErrorCodes.SERVER_ERROR).toBe('SERVER_ERROR');
+      expect(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR).toBe('UNKNOWN_ERROR');
+    });
+  });
+});
diff --git a/src/core/models/index.ts b/src/core/models/index.ts
index d6d3857b..6a1eebb4 100644
--- a/src/core/models/index.ts
+++ b/src/core/models/index.ts
@@ -8,3 +8,7 @@ export {
 } from './CredentialsManagerError';
 export { WebAuthError, WebAuthErrorCodes } from './WebAuthError';
 export { DPoPError, DPoPErrorCodes } from './DPoPError';
+export {
+  CustomTokenExchangeError,
+  CustomTokenExchangeErrorCodes,
+} from './CustomTokenExchangeError';
diff --git a/src/index.ts b/src/index.ts
index 28339a14..65fb8c94 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,6 +6,8 @@ export {
   WebAuthErrorCodes,
   DPoPError,
   DPoPErrorCodes,
+  CustomTokenExchangeError,
+  CustomTokenExchangeErrorCodes,
 } from './core/models';
 export { TimeoutError } from './core/utils/fetchWithTimeout';
 export { TokenType } from './types/common';
diff --git a/src/platforms/native/bridge/NativeBridgeManager.ts b/src/platforms/native/bridge/NativeBridgeManager.ts
index bb61a981..d19d3976 100644
--- a/src/platforms/native/bridge/NativeBridgeManager.ts
+++ b/src/platforms/native/bridge/NativeBridgeManager.ts
@@ -16,6 +16,7 @@ import {
 import {
   AuthError,
   Credentials as CredentialsModel,
+  CustomTokenExchangeError,
 } from '../../../core/models';
 import Auth0NativeModule from '../../../specs/NativeA0Auth0';
 import type { NativeModuleError } from '../../../core/interfaces';
@@ -230,14 +231,22 @@ export class NativeBridgeManager implements INativeBridge {
     scope?: string,
     organization?: string
   ): Promise<Credentials> {
-    const credential = await this.a0_call(
-      Auth0NativeModule.customTokenExchange.bind(Auth0NativeModule),
-      subjectToken,
-      subjectTokenType,
-      audience,
-      scope,
-      organization
-    );
-    return new CredentialsModel(credential);
+    try {
+      const credential = await this.a0_call(
+        Auth0NativeModule.customTokenExchange.bind(Auth0NativeModule),
+        subjectToken,
+        subjectTokenType,
+        audience,
+        scope,
+        organization
+      );
+      return new CredentialsModel(credential);
+    } catch (e) {
+      // Wrap AuthError in CustomTokenExchangeError for better error handling
+      if (e instanceof AuthError) {
+        throw new CustomTokenExchangeError(e);
+      }
+      throw CustomTokenExchangeError.from(e);
+    }
   }
 }
diff --git a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
index 43717362..19f0185e 100644
--- a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
+++ b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
@@ -1,5 +1,9 @@
 import { NativeBridgeManager } from '../NativeBridgeManager';
-import { AuthError, Credentials } from '../../../../core/models';
+import {
+  AuthError,
+  Credentials,
+  CustomTokenExchangeError,
+} from '../../../../core/models';
 import Auth0NativeModule from '../../../../specs/NativeA0Auth0';
 
 // Mock the entire spec file, which is our native module.
@@ -264,7 +268,7 @@ describe('NativeBridgeManager', () => {
       expect(credentials.tokenType).toBe('Bearer');
     });
 
-    it('should throw AuthError when native method fails', async () => {
+    it('should throw CustomTokenExchangeError when native method fails', async () => {
       const nativeError = {
         code: 'a0.token_exchange_failed',
         message: 'Token exchange failed',
@@ -275,14 +279,51 @@ describe('NativeBridgeManager', () => {
 
       await expect(
         bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token')
-      ).rejects.toThrow(AuthError);
+      ).rejects.toThrow(CustomTokenExchangeError);
 
       try {
         await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
       } catch (e) {
-        const authError = e as AuthError;
-        expect(authError.code).toBe('a0.token_exchange_failed');
-        expect(authError.message).toBe('Token exchange failed');
+        const tokenExchangeError = e as CustomTokenExchangeError;
+        expect(tokenExchangeError.type).toBe('TOKEN_EXCHANGE_DENIED');
+        expect(tokenExchangeError.message).toBe('Token exchange failed');
+        expect(tokenExchangeError.underlyingError.code).toBe(
+          'a0.token_exchange_failed'
+        );
+      }
+    });
+
+    it('should map invalid_grant error to INVALID_SUBJECT_TOKEN type', async () => {
+      const nativeError = {
+        code: 'invalid_grant',
+        message: 'The subject token is invalid',
+      };
+      MockedAuth0NativeModule.customTokenExchange.mockRejectedValue(
+        nativeError
+      );
+
+      try {
+        await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
+      } catch (e) {
+        const tokenExchangeError = e as CustomTokenExchangeError;
+        expect(tokenExchangeError.type).toBe('INVALID_SUBJECT_TOKEN');
+      }
+    });
+
+    it('should map unsupported_token_type error correctly', async () => {
+      const nativeError = {
+        code: 'unsupported_token_type',
+        message: 'The token type is not supported',
+      };
+      MockedAuth0NativeModule.customTokenExchange.mockRejectedValue(
+        nativeError
+      );
+
+      try {
+        await bridge.customTokenExchange('token', 'urn:unknown:type');
+      } catch (e) {
+        const tokenExchangeError = e as CustomTokenExchangeError;
+        expect(tokenExchangeError.type).toBe('UNSUPPORTED_TOKEN_TYPE');
       }
     });
   });
diff --git a/src/platforms/web/adapters/WebAuth0Client.ts b/src/platforms/web/adapters/WebAuth0Client.ts
index 6ab2b4a2..51a8bbc6 100644
--- a/src/platforms/web/adapters/WebAuth0Client.ts
+++ b/src/platforms/web/adapters/WebAuth0Client.ts
@@ -22,7 +22,11 @@ import {
 } from '../../../core/services';
 import { HttpClient } from '../../../core/services/HttpClient';
 import { TokenType } from '../../../types/common';
-import { AuthError, DPoPError } from '../../../core/models';
+import {
+  AuthError,
+  DPoPError,
+  CustomTokenExchangeError,
+} from '../../../core/models';
 
 export class WebAuth0Client implements IAuth0Client {
   readonly webAuth: WebWebAuthProvider;
@@ -217,27 +221,36 @@ export class WebAuth0Client implements IAuth0Client {
   async customTokenExchange(
     parameters: CustomTokenExchangeParameters
   ): Promise<Credentials> {
-    const { subjectToken, subjectTokenType, audience, scope, organization } =
-      parameters;
-
-    const response = await this.client.exchangeToken({
-      subject_token: subjectToken,
-      subject_token_type: subjectTokenType,
-      audience,
-      scope,
-      organization,
-    });
+    try {
+      const { subjectToken, subjectTokenType, audience, scope, organization } =
+        parameters;
 
-    // Convert expiresIn (seconds from now) to expiresAt (UNIX timestamp)
-    const expiresAt = Math.floor(Date.now() / 1000) + response.expires_in;
+      const response = await this.client.exchangeToken({
+        subject_token: subjectToken,
+        subject_token_type: subjectTokenType,
+        audience,
+        scope,
+        organization,
+      });
 
-    return {
-      accessToken: response.access_token,
-      idToken: response.id_token,
-      tokenType: (response.token_type as TokenType) ?? this.tokenType,
-      expiresAt,
-      scope: response.scope,
-      refreshToken: response.refresh_token,
-    };
+      // Convert expiresIn (seconds from now) to expiresAt (UNIX timestamp)
+      const expiresAt = Math.floor(Date.now() / 1000) + response.expires_in;
+
+      return {
+        accessToken: response.access_token,
+        idToken: response.id_token,
+        tokenType: (response.token_type as TokenType) ?? this.tokenType,
+        expiresAt,
+        scope: response.scope,
+        refreshToken: response.refresh_token,
+      };
+    } catch (e: any) {
+      const authError = new AuthError(
+        e.error ?? 'custom_token_exchange_failed',
+        e.error_description ?? e.message ?? 'Custom token exchange failed',
+        { json: e }
+      );
+      throw new CustomTokenExchangeError(authError);
+    }
   }
 }
diff --git a/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts b/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
index 3b6ffd9f..087f2d53 100644
--- a/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
+++ b/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
@@ -16,21 +16,47 @@ jest.mock('../../../../core/services/AuthenticationOrchestrator');
 jest.mock('../../../../core/services/ManagementApiOrchestrator');
 jest.mock('../../../../core/services/HttpClient');
 
-// Mock AuthError properly to support inheritance
-jest.mock('../../../../core/models', () => ({
-  AuthError: class MockAuthError extends Error {
+// Mock AuthError and CustomTokenExchangeError properly to support inheritance
+jest.mock('../../../../core/models', () => {
+  class MockAuthError extends Error {
+    code: string;
+    json: any;
     constructor(name: string, message: string, details?: any) {
       super(message);
       this.name = name;
+      this.code = details?.code ?? name;
+      this.json = details?.json;
       if (details) {
         Object.assign(this, details);
       }
     }
-  },
-  // Add other exports from models if needed
-  Credentials: jest.fn(),
-  Auth0User: jest.fn(),
-}));
+  }
+
+  class MockCustomTokenExchangeError extends Error {
+    type: string;
+    underlyingError: MockAuthError;
+    constructor(underlyingError: MockAuthError) {
+      super(underlyingError.message);
+      this.name = 'CustomTokenExchangeError';
+      this.underlyingError = underlyingError;
+      // Map error codes to types
+      const codeMap: Record<string, string> = {
+        'invalid_grant': 'INVALID_SUBJECT_TOKEN',
+        'a0.token_exchange_failed': 'TOKEN_EXCHANGE_DENIED',
+        'custom_token_exchange_failed': 'UNKNOWN_ERROR',
+      };
+      this.type = codeMap[underlyingError.code] ?? 'UNKNOWN_ERROR';
+    }
+  }
+
+  return {
+    AuthError: MockAuthError,
+    CustomTokenExchangeError: MockCustomTokenExchangeError,
+    // Add other exports from models if needed
+    Credentials: jest.fn(),
+    Auth0User: jest.fn(),
+  };
+});
 
 const MockAuth0Client = Auth0Client as jest.MockedClass<typeof Auth0Client>;
 const MockWebWebAuthProvider = WebWebAuthProvider as jest.MockedClass<
@@ -408,8 +434,12 @@ describe('WebAuth0Client', () => {
       expect(result.tokenType).toBe('DPoP');
     });
 
-    it('should propagate errors from exchangeToken', async () => {
-      const exchangeError = new Error('Token exchange failed');
+    it('should propagate errors from exchangeToken as CustomTokenExchangeError', async () => {
+      const exchangeError = {
+        error: 'invalid_grant',
+        error_description: 'Token exchange failed',
+        message: 'Token exchange failed',
+      };
       mockSpaClient.exchangeToken.mockRejectedValueOnce(exchangeError);
 
       await expect(
@@ -418,6 +448,37 @@ describe('WebAuth0Client', () => {
           subjectTokenType: 'urn:acme:legacy-token',
         })
       ).rejects.toThrow('Token exchange failed');
+
+      try {
+        await client.customTokenExchange({
+          subjectToken: 'bad-token',
+          subjectTokenType: 'urn:acme:legacy-token',
+        });
+      } catch (e: any) {
+        expect(e.name).toBe('CustomTokenExchangeError');
+        expect(e.type).toBe('INVALID_SUBJECT_TOKEN');
+      }
+    });
+
+    it('should wrap generic errors in CustomTokenExchangeError', async () => {
+      const genericError = new Error('Network error');
+      mockSpaClient.exchangeToken.mockRejectedValueOnce(genericError);
+
+      await expect(
+        client.customTokenExchange({
+          subjectToken: 'bad-token',
+          subjectTokenType: 'urn:acme:legacy-token',
+        })
+      ).rejects.toThrow('Network error');
+
+      try {
+        await client.customTokenExchange({
+          subjectToken: 'bad-token',
+          subjectTokenType: 'urn:acme:legacy-token',
+        });
+      } catch (e: any) {
+        expect(e.name).toBe('CustomTokenExchangeError');
+      }
     });
   });
 });

From f54a47a3d9bb05d31d84c5499b7ed259ede597d8 Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Thu, 15 Jan 2026 10:26:13 +0530
Subject: [PATCH 4/8] created a generalize Authentication exception

---
 EXAMPLES.md                                   | 106 ++++++--
 src/core/models/AuthenticationException.ts    | 233 ++++++++++++++++++
 src/core/models/CustomTokenExchangeError.ts   |  28 +--
 .../__tests__/AuthenticationException.spec.ts | 199 +++++++++++++++
 .../CustomTokenExchangeError.spec.ts          |  24 --
 src/core/models/index.ts                      |   6 +-
 src/index.ts                                  |   4 +-
 .../native/bridge/NativeBridgeManager.ts      |  17 +-
 .../__tests__/NativeBridgeManager.spec.ts     |  20 +-
 src/platforms/web/adapters/WebAuth0Client.ts  |   9 +-
 .../adapters/__tests__/WebAuth0Client.spec.ts |  22 +-
 src/types/parameters.ts                       |  18 +-
 12 files changed, 582 insertions(+), 104 deletions(-)
 create mode 100644 src/core/models/AuthenticationException.ts
 create mode 100644 src/core/models/__tests__/AuthenticationException.spec.ts

diff --git a/EXAMPLES.md b/EXAMPLES.md
index c90ea04f..391d2c7d 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -765,9 +765,9 @@ function App() {
 
 ## Custom Token Exchange (RFC 8693)
 
-Custom Token Exchange allows you to exchange external identity provider tokens for Auth0 tokens using the [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) specification. This enables scenarios where users authenticate with an external system and that token needs to be exchanged for Auth0 tokens.
+Custom Token Exchange allows you to exchange external identity provider tokens for Auth0 tokens using the [RFC 8693 OAuth 2.0 Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693) specification. This enables scenarios where users authenticate with an external system and that token needs to be exchanged for Auth0 tokens.
 
-> ⚠️ **Important**: The external token must be validated in Auth0 Actions using cryptographic verification. See the [Auth0 Custom Token Exchange documentation](https://auth0.com/docs/authenticate/login/custom-token-exchange) for setup instructions.
+> ⚠️ **Important**: The external token must be validated in Auth0 Actions using cryptographic verification. See the [Auth0 Custom Token Exchange documentation](https://auth0.com/docs/authenticate/custom-token-exchange) for setup instructions.
 
 ### Using Custom Token Exchange with Hooks
 
@@ -776,8 +776,8 @@ import React from 'react';
 import { Button, Alert } from 'react-native';
 import {
   useAuth0,
-  CustomTokenExchangeError,
-  CustomTokenExchangeErrorCodes,
+  AuthenticationException,
+  AuthenticationErrorCodes,
 } from 'react-native-auth0';
 
 function TokenExchangeScreen() {
@@ -795,24 +795,24 @@ function TokenExchangeScreen() {
 
       Alert.alert('Success', `Logged in as ${user?.name}`);
     } catch (e) {
-      if (e instanceof CustomTokenExchangeError) {
+      if (e instanceof AuthenticationException) {
         switch (e.type) {
-          case CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN:
+          case AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN:
             Alert.alert('Error', 'The external token is invalid or expired');
             break;
-          case CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE:
+          case AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE:
             Alert.alert('Error', 'The token type is not supported');
             break;
-          case CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED:
+          case AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED:
             Alert.alert(
               'Error',
               'Custom Token Exchange is not configured for this tenant'
             );
             break;
-          case CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED:
+          case AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED:
             Alert.alert('Error', 'Token validation failed in Auth0 Action');
             break;
-          case CustomTokenExchangeErrorCodes.NETWORK_ERROR:
+          case AuthenticationErrorCodes.NETWORK_ERROR:
             Alert.alert('Error', 'Network error. Please check your connection.');
             break;
           default:
@@ -832,8 +832,8 @@ function TokenExchangeScreen() {
 
 ```typescript
 import Auth0, {
-  CustomTokenExchangeError,
-  CustomTokenExchangeErrorCodes,
+  AuthenticationException,
+  AuthenticationErrorCodes,
 } from 'react-native-auth0';
 
 const auth0 = new Auth0({
@@ -853,14 +853,14 @@ async function exchangeExternalToken(externalToken: string) {
     console.log('Exchange successful:', credentials);
     return credentials;
   } catch (error) {
-    if (error instanceof CustomTokenExchangeError) {
+    if (error instanceof AuthenticationException) {
       // Access the underlying error details
       console.error('Error type:', error.type);
       console.error('Error message:', error.message);
       console.error('Underlying error code:', error.underlyingError.code);
 
       // Handle specific error types
-      if (error.type === CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN) {
+      if (error.type === AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN) {
         // Token is invalid or expired - prompt user to re-authenticate
         throw new Error('Please authenticate again with the external provider');
       }
@@ -885,16 +885,63 @@ const credentials = await customTokenExchange({
 
 ### Subject Token Type Requirements
 
-The `subjectTokenType` must be a namespaced URI under your organization's control. The following patterns are forbidden:
+The `subjectTokenType` parameter identifies the type of token being exchanged. Choose the appropriate type based on your use case:
 
-- `urn:ietf:params:oauth:*` (IETF reserved)
+#### For Standard OAuth Tokens (RFC 8693)
+
+When exchanging tokens from standard OAuth/OIDC providers (e.g., another Auth0 tenant, external IdP using standard protocols), use RFC 8693 standard token types:
+
+- `urn:ietf:params:oauth:token-type:jwt` - For JWTs (e.g., ID tokens, signed access tokens)
+- `urn:ietf:params:oauth:token-type:access_token` - For OAuth access tokens
+- `urn:ietf:params:oauth:token-type:refresh_token` - For OAuth refresh tokens
+- `urn:ietf:params:oauth:token-type:id_token` - For OIDC ID tokens
+- `urn:ietf:params:oauth:token-type:saml1` - For SAML 1.1 assertions
+- `urn:ietf:params:oauth:token-type:saml2` - For SAML 2.0 assertions
+
+#### For Custom/Legacy Tokens
+
+When exchanging tokens from custom systems or legacy identity providers that don't use standard OAuth formats, you MUST use organization-controlled URIs. The following patterns are **forbidden** for custom tokens:
+
+- `urn:ietf:params:oauth:*` (IETF reserved for RFC 8693 standard types only)
 - `https://auth0.com/*` (Auth0 reserved)
 - `urn:auth0:*` (Auth0 reserved)
 
-Valid examples:
+**Valid custom token type examples:**
+
+- `urn:acme:legacy-system-token` - For proprietary legacy system tokens
+- `urn:yourcompany:external-idp` - For external IdP tokens
+- `https://yourcompany.com/tokens/legacy` - Using your organization's domain
+
+#### Common Use Cases
+
+1. **Seamless Migration from Legacy IdP**: Exchange legacy refresh tokens using a custom type
+
+   ```typescript
+   await customTokenExchange({
+     subjectToken: legacyRefreshToken,
+     subjectTokenType: 'urn:acme:legacy-system-token',
+     scope: 'openid profile email offline_access',
+   });
+   ```
 
-- `urn:acme:legacy-system-token`
-- `https://yourcompany.com/tokens/legacy`
+2. **Re-use External Authentication**: Exchange ID token from external provider
+
+   ```typescript
+   await customTokenExchange({
+     subjectToken: externalIdToken,
+     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt', // Standard JWT
+     scope: 'openid profile email',
+   });
+   ```
+
+3. **Service-to-Service Token Exchange**: Exchange Auth0 access token for different audience
+   ```typescript
+   await customTokenExchange({
+     subjectToken: currentAccessToken,
+     subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
+     audience: 'https://api-b.example.com',
+   });
+   ```
 
 ### Error Codes Reference
 
@@ -919,6 +966,27 @@ These error codes are mapped from:
 - **Auth0-specific errors**: `a0.token_exchange_failed`, `a0.action_failed`, etc.
 - **Native SDK errors**: Platform-specific error codes from Auth0.swift and Auth0.Android
 
+### Auth0 Actions Validation
+
+Custom Token Exchange requires validation of the subject token in Auth0 Actions. The Action must:
+
+1. **Validate the subject token** cryptographically (verify signature, expiration, issuer, etc.)
+2. **Apply authorization policy** to determine if the exchange is allowed
+3. **Set the user** using one of the `api.authentication.setUser*()` methods
+
+For detailed examples of validating different token types in Actions, see:
+
+- [Auth0 Custom Token Exchange Documentation](https://auth0.com/docs/authenticate/custom-token-exchange)
+- [Example Use Cases](https://auth0.com/docs/authenticate/custom-token-exchange/cte-example-use-cases)
+
+**Security Best Practices:**
+
+- Use asymmetric algorithms (RS256, ES256) whenever possible
+- Store secrets in Actions Secrets, never hardcode them
+- Cache JWKS keys using `api.cache.set()` to improve performance
+- Validate token expiration, issuer, and audience claims
+- Implement rate limiting for failed validations using `api.access.rejectInvalidSubjectToken()`
+
 ## Native to Web SSO (Early Access)
 
 > ⚠️ **Early Access Feature**: Native to Web SSO is currently available in Early Access. To use this feature, you must have an Enterprise plan. For more information, see [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
diff --git a/src/core/models/AuthenticationException.ts b/src/core/models/AuthenticationException.ts
new file mode 100644
index 00000000..a256cc39
--- /dev/null
+++ b/src/core/models/AuthenticationException.ts
@@ -0,0 +1,233 @@
+import { AuthError } from './AuthError';
+
+/**
+ * Platform-agnostic error code constants for Authentication API operations.
+ *
+ * Use these constants for type-safe error handling when working with authentication operations.
+ * Each constant corresponds to a specific error type in the {@link AuthenticationException.type} property.
+ *
+ * @example
+ * ```typescript
+ * import { AuthenticationException, AuthenticationErrorCodes } from 'react-native-auth0';
+ *
+ * try {
+ *   const credentials = await auth0.auth.login({
+ *     username: 'user@example.com',
+ *     password: 'password',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof AuthenticationException) {
+ *     switch (e.type) {
+ *       case AuthenticationErrorCodes.INVALID_CREDENTIALS:
+ *         // Invalid username or password
+ *         break;
+ *       case AuthenticationErrorCodes.INVALID_GRANT:
+ *         // Token or grant is invalid
+ *         break;
+ *       case AuthenticationErrorCodes.PASSWORD_LEAKED:
+ *         // Password was found in a data breach
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link AuthenticationException}
+ * @see {@link https://auth0.com/docs/api/authentication|Authentication API}
+ */
+export const AuthenticationErrorCodes = {
+  // General authentication errors
+  /** Invalid credentials provided (username/password/code/token) */
+  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+  /** Invalid or expired grant/token */
+  INVALID_GRANT: 'INVALID_GRANT',
+  /** Invalid request parameters */
+  INVALID_REQUEST: 'INVALID_REQUEST',
+  /** Access denied by authorization server or Actions/Rules */
+  ACCESS_DENIED: 'ACCESS_DENIED',
+  /** Unauthorized client */
+  UNAUTHORIZED_CLIENT: 'UNAUTHORIZED_CLIENT',
+
+  // Password-related errors
+  /** Password does not meet strength requirements */
+  PASSWORD_STRENGTH: 'PASSWORD_STRENGTH',
+  /** Password was previously used */
+  PASSWORD_ALREADY_USED: 'PASSWORD_ALREADY_USED',
+  /** Password was found in a data breach */
+  PASSWORD_LEAKED: 'PASSWORD_LEAKED',
+
+  // MFA-related errors
+  /** MFA is required */
+  MFA_REQUIRED: 'MFA_REQUIRED',
+  /** Invalid MFA code */
+  MFA_INVALID_CODE: 'MFA_INVALID_CODE',
+  /** MFA token is invalid or expired */
+  MFA_TOKEN_INVALID: 'MFA_TOKEN_INVALID',
+
+  // Token Exchange specific errors
+  /** The subject token is invalid, malformed, or expired */
+  INVALID_SUBJECT_TOKEN: 'INVALID_SUBJECT_TOKEN',
+  /** The subject token type is not supported or not recognized */
+  UNSUPPORTED_TOKEN_TYPE: 'UNSUPPORTED_TOKEN_TYPE',
+  /** Custom Token Exchange is not configured or enabled */
+  TOKEN_EXCHANGE_NOT_CONFIGURED: 'TOKEN_EXCHANGE_NOT_CONFIGURED',
+  /** Token validation in Auth0 Action failed */
+  TOKEN_VALIDATION_FAILED: 'TOKEN_VALIDATION_FAILED',
+  /** Token exchange request was denied */
+  TOKEN_EXCHANGE_DENIED: 'TOKEN_EXCHANGE_DENIED',
+
+  // Scope and audience errors
+  /** The requested audience is invalid or not allowed */
+  INVALID_AUDIENCE: 'INVALID_AUDIENCE',
+  /** The requested scope is invalid or not allowed */
+  INVALID_SCOPE: 'INVALID_SCOPE',
+
+  // Rate limiting and security
+  /** Too many authentication attempts */
+  TOO_MANY_ATTEMPTS: 'TOO_MANY_ATTEMPTS',
+  /** Additional verification is required */
+  VERIFICATION_REQUIRED: 'VERIFICATION_REQUIRED',
+  /** Login is required (for silent authentication) */
+  LOGIN_REQUIRED: 'LOGIN_REQUIRED',
+
+  // Network and server errors
+  /** Network error occurred */
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  /** The authorization server encountered an internal error */
+  SERVER_ERROR: 'SERVER_ERROR',
+
+  /** Unknown or uncategorized authentication error */
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+} as const;
+
+/**
+ * Type for the values of AuthenticationErrorCodes.
+ */
+export type AuthenticationErrorCode =
+  (typeof AuthenticationErrorCodes)[keyof typeof AuthenticationErrorCodes];
+
+const ERROR_CODE_MAP: Record<string, AuthenticationErrorCode> = {
+  // OAuth 2.0 / RFC 6749 standard error codes
+  'invalid_request': AuthenticationErrorCodes.INVALID_REQUEST,
+  'invalid_grant': AuthenticationErrorCodes.INVALID_GRANT,
+  'invalid_token': AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
+  'invalid_client': AuthenticationErrorCodes.INVALID_CREDENTIALS,
+  'invalid_credentials': AuthenticationErrorCodes.INVALID_CREDENTIALS,
+  'unauthorized_client': AuthenticationErrorCodes.UNAUTHORIZED_CLIENT,
+  'unsupported_grant_type': AuthenticationErrorCodes.INVALID_REQUEST,
+  'invalid_scope': AuthenticationErrorCodes.INVALID_SCOPE,
+  'access_denied': AuthenticationErrorCodes.ACCESS_DENIED,
+  'server_error': AuthenticationErrorCodes.SERVER_ERROR,
+
+  // RFC 8693 Token Exchange specific
+  'unsupported_token_type': AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE,
+  'invalid_target': AuthenticationErrorCodes.INVALID_AUDIENCE,
+
+  // Auth0-specific error codes - General
+  'unauthorized': AuthenticationErrorCodes.ACCESS_DENIED,
+
+  // Auth0-specific error codes - MFA
+  'a0.mfa_required': AuthenticationErrorCodes.MFA_REQUIRED,
+  'a0.mfa_invalid_code': AuthenticationErrorCodes.MFA_INVALID_CODE,
+  'a0.mfa_token_invalid': AuthenticationErrorCodes.MFA_TOKEN_INVALID,
+  'mfa_required': AuthenticationErrorCodes.MFA_REQUIRED,
+  'mfa_token_invalid': AuthenticationErrorCodes.MFA_TOKEN_INVALID,
+  'expired_token': AuthenticationErrorCodes.MFA_TOKEN_INVALID,
+
+  // Auth0-specific error codes - Password
+  'invalid_password': AuthenticationErrorCodes.INVALID_CREDENTIALS,
+  'password_leaked': AuthenticationErrorCodes.PASSWORD_LEAKED,
+  'password_strength_error': AuthenticationErrorCodes.PASSWORD_STRENGTH,
+  'password_history_error': AuthenticationErrorCodes.PASSWORD_ALREADY_USED,
+  'password_already_used': AuthenticationErrorCodes.PASSWORD_ALREADY_USED,
+
+  // Auth0-specific error codes - Rate Limiting & Verification
+  'too_many_attempts': AuthenticationErrorCodes.TOO_MANY_ATTEMPTS,
+  'requires_verification': AuthenticationErrorCodes.VERIFICATION_REQUIRED,
+  'verification_required': AuthenticationErrorCodes.VERIFICATION_REQUIRED,
+  'login_required': AuthenticationErrorCodes.LOGIN_REQUIRED,
+
+  // Token Exchange specific Auth0 codes
+  'a0.token_exchange_failed': AuthenticationErrorCodes.TOKEN_EXCHANGE_DENIED,
+  'a0.token_exchange_not_enabled':
+    AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+  'a0.invalid_subject_token': AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
+  'a0.subject_token_expired': AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
+  'a0.subject_token_validation_failed':
+    AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED,
+  'a0.action_failed': AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED,
+
+  // Network errors
+  'a0.network_error': AuthenticationErrorCodes.NETWORK_ERROR,
+};
+
+/**
+ * Represents an error that occurred during an Authentication API operation.
+ *
+ * This error class provides structured error handling for authentication operations,
+ * with platform-agnostic error codes that normalize errors from iOS, Android, and web platforms.
+ *
+ * The Authentication API handles various operations including:
+ * - Login (username/password, passwordless, social)
+ * - Token exchange and refresh
+ * - Multi-factor authentication
+ * - Password management
+ *
+ * The `type` property provides a normalized, platform-agnostic error code that
+ * applications can use for consistent error handling across iOS, Android, and Web.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   AuthenticationException,
+ *   AuthenticationErrorCodes
+ * } from 'react-native-auth0';
+ *
+ * try {
+ *   const credentials = await auth0.auth.login({
+ *     username: 'user@example.com',
+ *     password: 'password',
+ *     realm: 'Username-Password-Authentication',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof AuthenticationException) {
+ *     console.log('Error type:', e.type);
+ *     console.log('Error message:', e.message);
+ *
+ *     if (e.type === AuthenticationErrorCodes.INVALID_CREDENTIALS) {
+ *       // Invalid username or password
+ *     } else if (e.type === AuthenticationErrorCodes.PASSWORD_LEAKED) {
+ *       // Password found in breach database
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link AuthenticationErrorCodes}
+ * @see {@link https://auth0.com/docs/api/authentication|Authentication API}
+ */
+export class AuthenticationException extends AuthError {
+  /**
+   * A normalized error type that is consistent across platforms.
+   * This can be used for reliable error handling in application code.
+   */
+  public readonly type: AuthenticationErrorCode;
+
+  /**
+   * Constructs a new AuthenticationException instance from an AuthError.
+   *
+   * @param originalError The original AuthError that occurred during an authentication operation.
+   */
+  constructor(originalError: AuthError) {
+    super(originalError.name, originalError.message, {
+      status: originalError.status,
+      code: originalError.code,
+      json: originalError.json,
+    });
+
+    // Map the original error code to a normalized type
+    this.type =
+      ERROR_CODE_MAP[originalError.code] ||
+      AuthenticationErrorCodes.UNKNOWN_ERROR;
+  }
+}
diff --git a/src/core/models/CustomTokenExchangeError.ts b/src/core/models/CustomTokenExchangeError.ts
index e25b935d..4fef0965 100644
--- a/src/core/models/CustomTokenExchangeError.ts
+++ b/src/core/models/CustomTokenExchangeError.ts
@@ -11,9 +11,10 @@ import { AuthError } from './AuthError';
  * import { CustomTokenExchangeError, CustomTokenExchangeErrorCodes } from 'react-native-auth0';
  *
  * try {
+ *   // Exchange a custom legacy token
  *   const credentials = await auth0.customTokenExchange({
  *     subjectToken: externalToken,
- *     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
+ *     subjectTokenType: 'urn:acme:legacy-system-token',
  *   });
  * } catch (e) {
  *   if (e instanceof CustomTokenExchangeError) {
@@ -33,7 +34,7 @@ import { AuthError } from './AuthError';
  * ```
  *
  * @see {@link CustomTokenExchangeError}
- * @see {@link https://www.rfc-editor.org/rfc/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
  */
 export const CustomTokenExchangeErrorCodes = {
   /** The subject token is invalid, malformed, or expired */
@@ -65,7 +66,7 @@ export type CustomTokenExchangeErrorCode =
   (typeof CustomTokenExchangeErrorCodes)[keyof typeof CustomTokenExchangeErrorCodes];
 
 const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
-  // --- RFC 8693 OAuth 2.0 Token Exchange error codes ---
+  // RFC 8693 OAuth 2.0 Token Exchange standard error codes
   'invalid_request': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
   'invalid_grant': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
   'invalid_token': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
@@ -78,7 +79,7 @@ const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
     CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
   'server_error': CustomTokenExchangeErrorCodes.SERVER_ERROR,
 
-  // --- Auth0-specific error codes ---
+  // Auth0-specific error codes
   'a0.token_exchange_failed':
     CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
   'a0.token_exchange_not_enabled':
@@ -90,21 +91,7 @@ const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
   'a0.subject_token_validation_failed':
     CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
   'a0.action_failed': CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-
-  // --- Native SDK codes (iOS/Android) ---
-  'INVALID_SUBJECT_TOKEN': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-  'UNSUPPORTED_TOKEN_TYPE':
-    CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
-  'TOKEN_EXCHANGE_FAILED': CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
-  'TOKEN_EXCHANGE_NOT_CONFIGURED':
-    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-  'TOKEN_VALIDATION_FAILED':
-    CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-
-  // --- Network errors ---
   'a0.network_error': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
-  'NETWORK_ERROR': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
-  'network_error': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
 };
 
 /**
@@ -128,6 +115,7 @@ const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
  * } from 'react-native-auth0';
  *
  * try {
+ *   // Exchange a standard JWT from external OIDC provider
  *   const credentials = await auth0.customTokenExchange({
  *     subjectToken: externalToken,
  *     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
@@ -146,8 +134,8 @@ const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
  * ```
  *
  * @see {@link CustomTokenExchangeErrorCodes}
- * @see {@link https://www.rfc-editor.org/rfc/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
- * @see {@link https://auth0.com/docs/authenticate/login/custom-token-exchange|Auth0 Custom Token Exchange}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
+ * @see {@link https://auth0.com/docs/authenticate/custom-token-exchange|Auth0 Custom Token Exchange}
  */
 export class CustomTokenExchangeError extends Error {
   /**
diff --git a/src/core/models/__tests__/AuthenticationException.spec.ts b/src/core/models/__tests__/AuthenticationException.spec.ts
new file mode 100644
index 00000000..5bf6d627
--- /dev/null
+++ b/src/core/models/__tests__/AuthenticationException.spec.ts
@@ -0,0 +1,199 @@
+import {
+  AuthenticationException,
+  AuthenticationErrorCodes,
+} from '../AuthenticationException';
+import { AuthError } from '../AuthError';
+
+describe('AuthenticationException', () => {
+  describe('constructor', () => {
+    it('should create error with correct name', () => {
+      const authError = new AuthError('invalid_grant', 'Token expired', {
+        code: 'invalid_grant',
+      });
+      const error = new AuthenticationException(authError);
+
+      expect(error.name).toBe('invalid_grant');
+    });
+
+    it('should preserve the error message', () => {
+      const authError = new AuthError('invalid_grant', 'Token expired', {
+        code: 'invalid_grant',
+      });
+      const error = new AuthenticationException(authError);
+
+      expect(error.message).toBe('Token expired');
+    });
+
+    it('should preserve the error code', () => {
+      const authError = new AuthError('invalid_grant', 'Token expired', {
+        code: 'invalid_grant',
+      });
+      const error = new AuthenticationException(authError);
+
+      expect(error.code).toBe('invalid_grant');
+    });
+  });
+
+  describe('error code mapping', () => {
+    it.each([
+      // OAuth 2.0 / RFC 6749 error codes - General auth errors
+      ['invalid_request', AuthenticationErrorCodes.INVALID_REQUEST],
+      ['invalid_grant', AuthenticationErrorCodes.INVALID_GRANT],
+      ['invalid_credentials', AuthenticationErrorCodes.INVALID_CREDENTIALS],
+      ['access_denied', AuthenticationErrorCodes.ACCESS_DENIED],
+      ['unauthorized_client', AuthenticationErrorCodes.UNAUTHORIZED_CLIENT],
+      ['invalid_scope', AuthenticationErrorCodes.INVALID_SCOPE],
+      ['invalid_token', AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN],
+
+      // Token exchange specific errors
+      ['server_error', AuthenticationErrorCodes.SERVER_ERROR],
+      [
+        'a0.token_exchange_failed',
+        AuthenticationErrorCodes.TOKEN_EXCHANGE_DENIED,
+      ],
+      [
+        'a0.token_exchange_not_enabled',
+        AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
+      ],
+      [
+        'unsupported_token_type',
+        AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE,
+      ],
+      ['invalid_target', AuthenticationErrorCodes.INVALID_AUDIENCE],
+      [
+        'a0.invalid_subject_token',
+        AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
+      ],
+      [
+        'a0.subject_token_expired',
+        AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
+      ],
+      [
+        'a0.subject_token_validation_failed',
+        AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED,
+      ],
+      ['a0.action_failed', AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED],
+
+      // Password errors
+      ['password_strength_error', AuthenticationErrorCodes.PASSWORD_STRENGTH],
+      ['password_leaked', AuthenticationErrorCodes.PASSWORD_LEAKED],
+      ['password_already_used', AuthenticationErrorCodes.PASSWORD_ALREADY_USED],
+
+      // MFA errors
+      ['a0.mfa_required', AuthenticationErrorCodes.MFA_REQUIRED],
+      ['mfa_required', AuthenticationErrorCodes.MFA_REQUIRED],
+      ['a0.mfa_invalid_code', AuthenticationErrorCodes.MFA_INVALID_CODE],
+      ['a0.mfa_token_invalid', AuthenticationErrorCodes.MFA_TOKEN_INVALID],
+
+      // Rate limiting and verification
+      ['too_many_attempts', AuthenticationErrorCodes.TOO_MANY_ATTEMPTS],
+      ['verification_required', AuthenticationErrorCodes.VERIFICATION_REQUIRED],
+      ['login_required', AuthenticationErrorCodes.LOGIN_REQUIRED],
+
+      // Network errors
+      ['a0.network_error', AuthenticationErrorCodes.NETWORK_ERROR],
+    ])('should map "%s" to %s', (errorCode, expectedType) => {
+      const authError = new AuthError(errorCode, 'Test error', {
+        code: errorCode,
+      });
+      const error = new AuthenticationException(authError);
+
+      expect(error.type).toBe(expectedType);
+    });
+
+    it('should map unknown error codes to UNKNOWN_ERROR', () => {
+      const authError = new AuthError('some_unknown_code', 'Unknown error', {
+        code: 'some_unknown_code',
+      });
+      const error = new AuthenticationException(authError);
+
+      expect(error.type).toBe(AuthenticationErrorCodes.UNKNOWN_ERROR);
+    });
+
+    it('should use default code when code is not explicitly provided', () => {
+      // When code is not provided in details, AuthError defaults to 'unknown_error'
+      const authError = new AuthError('invalid_grant', 'Test error');
+      const error = new AuthenticationException(authError);
+
+      // Since code defaults to 'unknown_error', it maps to UNKNOWN_ERROR
+      expect(error.type).toBe(AuthenticationErrorCodes.UNKNOWN_ERROR);
+    });
+
+    it('should prefer explicit code over name when mapping error type', () => {
+      const authError = new AuthError('some_name', 'Test error', {
+        code: 'invalid_grant',
+      });
+      const error = new AuthenticationException(authError);
+
+      expect(error.type).toBe(AuthenticationErrorCodes.INVALID_GRANT);
+    });
+  });
+
+  describe('AuthenticationErrorCodes', () => {
+    it('should export all expected error codes', () => {
+      // General auth errors
+      expect(AuthenticationErrorCodes.INVALID_REQUEST).toBe('INVALID_REQUEST');
+      expect(AuthenticationErrorCodes.INVALID_GRANT).toBe('INVALID_GRANT');
+      expect(AuthenticationErrorCodes.INVALID_CREDENTIALS).toBe(
+        'INVALID_CREDENTIALS'
+      );
+      expect(AuthenticationErrorCodes.ACCESS_DENIED).toBe('ACCESS_DENIED');
+      expect(AuthenticationErrorCodes.UNAUTHORIZED_CLIENT).toBe(
+        'UNAUTHORIZED_CLIENT'
+      );
+
+      // Token exchange errors
+      expect(AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN).toBe(
+        'INVALID_SUBJECT_TOKEN'
+      );
+      expect(AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE).toBe(
+        'UNSUPPORTED_TOKEN_TYPE'
+      );
+      expect(AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED).toBe(
+        'TOKEN_EXCHANGE_NOT_CONFIGURED'
+      );
+      expect(AuthenticationErrorCodes.INVALID_AUDIENCE).toBe(
+        'INVALID_AUDIENCE'
+      );
+      expect(AuthenticationErrorCodes.INVALID_SCOPE).toBe('INVALID_SCOPE');
+      expect(AuthenticationErrorCodes.TOKEN_EXCHANGE_DENIED).toBe(
+        'TOKEN_EXCHANGE_DENIED'
+      );
+      expect(AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED).toBe(
+        'TOKEN_VALIDATION_FAILED'
+      );
+
+      // Password errors
+      expect(AuthenticationErrorCodes.PASSWORD_STRENGTH).toBe(
+        'PASSWORD_STRENGTH'
+      );
+      expect(AuthenticationErrorCodes.PASSWORD_LEAKED).toBe('PASSWORD_LEAKED');
+      expect(AuthenticationErrorCodes.PASSWORD_ALREADY_USED).toBe(
+        'PASSWORD_ALREADY_USED'
+      );
+
+      // MFA errors
+      expect(AuthenticationErrorCodes.MFA_REQUIRED).toBe('MFA_REQUIRED');
+      expect(AuthenticationErrorCodes.MFA_INVALID_CODE).toBe(
+        'MFA_INVALID_CODE'
+      );
+      expect(AuthenticationErrorCodes.MFA_TOKEN_INVALID).toBe(
+        'MFA_TOKEN_INVALID'
+      );
+
+      // Rate limiting
+      expect(AuthenticationErrorCodes.TOO_MANY_ATTEMPTS).toBe(
+        'TOO_MANY_ATTEMPTS'
+      );
+      expect(AuthenticationErrorCodes.VERIFICATION_REQUIRED).toBe(
+        'VERIFICATION_REQUIRED'
+      );
+      expect(AuthenticationErrorCodes.LOGIN_REQUIRED).toBe('LOGIN_REQUIRED');
+
+      // Common errors
+      expect(AuthenticationErrorCodes.NETWORK_ERROR).toBe('NETWORK_ERROR');
+      expect(AuthenticationErrorCodes.SERVER_ERROR).toBe('SERVER_ERROR');
+      expect(AuthenticationErrorCodes.UNKNOWN_ERROR).toBe('UNKNOWN_ERROR');
+    });
+  });
+});
diff --git a/src/core/models/__tests__/CustomTokenExchangeError.spec.ts b/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
index 3d48b2ee..cb1506d9 100644
--- a/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
+++ b/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
@@ -79,32 +79,8 @@ describe('CustomTokenExchangeError', () => {
         CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
       ],
 
-      // Native SDK codes
-      [
-        'INVALID_SUBJECT_TOKEN',
-        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-      ],
-      [
-        'UNSUPPORTED_TOKEN_TYPE',
-        CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
-      ],
-      [
-        'TOKEN_EXCHANGE_FAILED',
-        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
-      ],
-      [
-        'TOKEN_EXCHANGE_NOT_CONFIGURED',
-        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-      ],
-      [
-        'TOKEN_VALIDATION_FAILED',
-        CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-      ],
-
       // Network errors
       ['a0.network_error', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
-      ['NETWORK_ERROR', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
-      ['network_error', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
     ])('should map "%s" to %s', (errorCode, expectedType) => {
       const authError = new AuthError(errorCode, 'Test error', {
         code: errorCode,
diff --git a/src/core/models/index.ts b/src/core/models/index.ts
index 6a1eebb4..6da94065 100644
--- a/src/core/models/index.ts
+++ b/src/core/models/index.ts
@@ -9,6 +9,6 @@ export {
 export { WebAuthError, WebAuthErrorCodes } from './WebAuthError';
 export { DPoPError, DPoPErrorCodes } from './DPoPError';
 export {
-  CustomTokenExchangeError,
-  CustomTokenExchangeErrorCodes,
-} from './CustomTokenExchangeError';
+  AuthenticationException,
+  AuthenticationErrorCodes,
+} from './AuthenticationException';
diff --git a/src/index.ts b/src/index.ts
index 65fb8c94..13c0ba3c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,8 +6,8 @@ export {
   WebAuthErrorCodes,
   DPoPError,
   DPoPErrorCodes,
-  CustomTokenExchangeError,
-  CustomTokenExchangeErrorCodes,
+  AuthenticationException,
+  AuthenticationErrorCodes,
 } from './core/models';
 export { TimeoutError } from './core/utils/fetchWithTimeout';
 export { TokenType } from './types/common';
diff --git a/src/platforms/native/bridge/NativeBridgeManager.ts b/src/platforms/native/bridge/NativeBridgeManager.ts
index c5d159b1..f3151b21 100644
--- a/src/platforms/native/bridge/NativeBridgeManager.ts
+++ b/src/platforms/native/bridge/NativeBridgeManager.ts
@@ -16,7 +16,7 @@ import {
 import {
   AuthError,
   Credentials as CredentialsModel,
-  CustomTokenExchangeError,
+  AuthenticationException,
 } from '../../../core/models';
 import Auth0NativeModule from '../../../specs/NativeA0Auth0';
 import type { NativeModuleError } from '../../../core/interfaces';
@@ -244,11 +244,16 @@ export class NativeBridgeManager implements INativeBridge {
       );
       return new CredentialsModel(credential);
     } catch (e) {
-      // Wrap AuthError in CustomTokenExchangeError for better error handling
-      if (e instanceof AuthError) {
-        throw new CustomTokenExchangeError(e);
-      }
-      throw CustomTokenExchangeError.from(e);
+      // Wrap AuthError in AuthenticationException for better error handling
+      const authError =
+        e instanceof AuthError
+          ? e
+          : new AuthError(
+              'authentication_error',
+              e instanceof Error ? e.message : String(e),
+              { code: 'authentication_error', json: e }
+            );
+      throw new AuthenticationException(authError);
     }
   }
 }
diff --git a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
index 19f0185e..1dc89dd7 100644
--- a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
+++ b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
@@ -2,7 +2,7 @@ import { NativeBridgeManager } from '../NativeBridgeManager';
 import {
   AuthError,
   Credentials,
-  CustomTokenExchangeError,
+  AuthenticationException,
 } from '../../../../core/models';
 import Auth0NativeModule from '../../../../specs/NativeA0Auth0';
 
@@ -268,7 +268,7 @@ describe('NativeBridgeManager', () => {
       expect(credentials.tokenType).toBe('Bearer');
     });
 
-    it('should throw CustomTokenExchangeError when native method fails', async () => {
+    it('should throw AuthenticationException when native method fails', async () => {
       const nativeError = {
         code: 'a0.token_exchange_failed',
         message: 'Token exchange failed',
@@ -279,21 +279,19 @@ describe('NativeBridgeManager', () => {
 
       await expect(
         bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token')
-      ).rejects.toThrow(CustomTokenExchangeError);
+      ).rejects.toThrow(AuthenticationException);
 
       try {
         await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
       } catch (e) {
-        const tokenExchangeError = e as CustomTokenExchangeError;
+        const tokenExchangeError = e as AuthenticationException;
         expect(tokenExchangeError.type).toBe('TOKEN_EXCHANGE_DENIED');
         expect(tokenExchangeError.message).toBe('Token exchange failed');
-        expect(tokenExchangeError.underlyingError.code).toBe(
-          'a0.token_exchange_failed'
-        );
+        expect(tokenExchangeError.code).toBe('a0.token_exchange_failed');
       }
     });
 
-    it('should map invalid_grant error to INVALID_SUBJECT_TOKEN type', async () => {
+    it('should map invalid_grant error to INVALID_GRANT type', async () => {
       const nativeError = {
         code: 'invalid_grant',
         message: 'The subject token is invalid',
@@ -305,8 +303,8 @@ describe('NativeBridgeManager', () => {
       try {
         await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
       } catch (e) {
-        const tokenExchangeError = e as CustomTokenExchangeError;
-        expect(tokenExchangeError.type).toBe('INVALID_SUBJECT_TOKEN');
+        const tokenExchangeError = e as AuthenticationException;
+        expect(tokenExchangeError.type).toBe('INVALID_GRANT');
       }
     });
 
@@ -322,7 +320,7 @@ describe('NativeBridgeManager', () => {
       try {
         await bridge.customTokenExchange('token', 'urn:unknown:type');
       } catch (e) {
-        const tokenExchangeError = e as CustomTokenExchangeError;
+        const tokenExchangeError = e as AuthenticationException;
         expect(tokenExchangeError.type).toBe('UNSUPPORTED_TOKEN_TYPE');
       }
     });
diff --git a/src/platforms/web/adapters/WebAuth0Client.ts b/src/platforms/web/adapters/WebAuth0Client.ts
index 51a8bbc6..467c578c 100644
--- a/src/platforms/web/adapters/WebAuth0Client.ts
+++ b/src/platforms/web/adapters/WebAuth0Client.ts
@@ -25,7 +25,7 @@ import { TokenType } from '../../../types/common';
 import {
   AuthError,
   DPoPError,
-  CustomTokenExchangeError,
+  AuthenticationException,
 } from '../../../core/models';
 
 export class WebAuth0Client implements IAuth0Client {
@@ -225,11 +225,14 @@ export class WebAuth0Client implements IAuth0Client {
       const { subjectToken, subjectTokenType, audience, scope, organization } =
         parameters;
 
+      // Apply default scope if not provided for consistency with native platforms
+      const finalScope = scope ?? 'openid profile email';
+
       const response = await this.client.exchangeToken({
         subject_token: subjectToken,
         subject_token_type: subjectTokenType,
         audience,
-        scope,
+        scope: finalScope,
         organization,
       });
 
@@ -250,7 +253,7 @@ export class WebAuth0Client implements IAuth0Client {
         e.error_description ?? e.message ?? 'Custom token exchange failed',
         { json: e }
       );
-      throw new CustomTokenExchangeError(authError);
+      throw new AuthenticationException(authError);
     }
   }
 }
diff --git a/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts b/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
index 087f2d53..aafbf952 100644
--- a/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
+++ b/src/platforms/web/adapters/__tests__/WebAuth0Client.spec.ts
@@ -16,7 +16,7 @@ jest.mock('../../../../core/services/AuthenticationOrchestrator');
 jest.mock('../../../../core/services/ManagementApiOrchestrator');
 jest.mock('../../../../core/services/HttpClient');
 
-// Mock AuthError and CustomTokenExchangeError properly to support inheritance
+// Mock AuthError and AuthenticationException properly to support inheritance
 jest.mock('../../../../core/models', () => {
   class MockAuthError extends Error {
     code: string;
@@ -32,16 +32,16 @@ jest.mock('../../../../core/models', () => {
     }
   }
 
-  class MockCustomTokenExchangeError extends Error {
+  class MockAuthenticationException extends Error {
     type: string;
     underlyingError: MockAuthError;
     constructor(underlyingError: MockAuthError) {
       super(underlyingError.message);
-      this.name = 'CustomTokenExchangeError';
+      this.name = 'AuthenticationException';
       this.underlyingError = underlyingError;
       // Map error codes to types
       const codeMap: Record<string, string> = {
-        'invalid_grant': 'INVALID_SUBJECT_TOKEN',
+        'invalid_grant': 'INVALID_GRANT',
         'a0.token_exchange_failed': 'TOKEN_EXCHANGE_DENIED',
         'custom_token_exchange_failed': 'UNKNOWN_ERROR',
       };
@@ -51,7 +51,7 @@ jest.mock('../../../../core/models', () => {
 
   return {
     AuthError: MockAuthError,
-    CustomTokenExchangeError: MockCustomTokenExchangeError,
+    AuthenticationException: MockAuthenticationException,
     // Add other exports from models if needed
     Credentials: jest.fn(),
     Auth0User: jest.fn(),
@@ -384,7 +384,7 @@ describe('WebAuth0Client', () => {
         subject_token: 'external-token',
         subject_token_type: 'urn:acme:legacy-token',
         audience: undefined,
-        scope: undefined,
+        scope: 'openid profile email', // Default scope applied
         organization: undefined,
       });
     });
@@ -434,7 +434,7 @@ describe('WebAuth0Client', () => {
       expect(result.tokenType).toBe('DPoP');
     });
 
-    it('should propagate errors from exchangeToken as CustomTokenExchangeError', async () => {
+    it('should propagate errors from exchangeToken as AuthenticationException', async () => {
       const exchangeError = {
         error: 'invalid_grant',
         error_description: 'Token exchange failed',
@@ -455,12 +455,12 @@ describe('WebAuth0Client', () => {
           subjectTokenType: 'urn:acme:legacy-token',
         });
       } catch (e: any) {
-        expect(e.name).toBe('CustomTokenExchangeError');
-        expect(e.type).toBe('INVALID_SUBJECT_TOKEN');
+        expect(e.name).toBe('AuthenticationException');
+        expect(e.type).toBe('INVALID_GRANT');
       }
     });
 
-    it('should wrap generic errors in CustomTokenExchangeError', async () => {
+    it('should wrap generic errors in AuthenticationException', async () => {
       const genericError = new Error('Network error');
       mockSpaClient.exchangeToken.mockRejectedValueOnce(genericError);
 
@@ -477,7 +477,7 @@ describe('WebAuth0Client', () => {
           subjectTokenType: 'urn:acme:legacy-token',
         });
       } catch (e: any) {
-        expect(e.name).toBe('CustomTokenExchangeError');
+        expect(e.name).toBe('AuthenticationException');
       }
     });
   });
diff --git a/src/types/parameters.ts b/src/types/parameters.ts
index 63262b0b..948d4e35 100644
--- a/src/types/parameters.ts
+++ b/src/types/parameters.ts
@@ -122,7 +122,7 @@ export interface ExchangeNativeSocialParameters extends RequestOptions {
  * providers for Auth0 tokens. The external token must be validated in Auth0
  * Actions using cryptographic verification.
  *
- * @see https://auth0.com/docs/authenticate/login/custom-token-exchange
+ * @see https://auth0.com/docs/authenticate/custom-token-exchange
  */
 export interface CustomTokenExchangeParameters {
   /**
@@ -133,14 +133,22 @@ export interface CustomTokenExchangeParameters {
 
   /**
    * The type identifier for the subject token being exchanged.
-   * Must be a namespaced URI under your organization's control.
    *
-   * Forbidden patterns:
-   * - `urn:ietf:params:oauth:*` (IETF reserved)
+   * For standard OAuth tokens (e.g., from OIDC providers), use RFC 8693 standard types:
+   * - `urn:ietf:params:oauth:token-type:jwt` - For JWTs (ID tokens, signed access tokens)
+   * - `urn:ietf:params:oauth:token-type:access_token` - For OAuth access tokens
+   * - `urn:ietf:params:oauth:token-type:refresh_token` - For OAuth refresh tokens
+   * - `urn:ietf:params:oauth:token-type:id_token` - For OIDC ID tokens
+   * - `urn:ietf:params:oauth:token-type:saml1` - For SAML 1.1 assertions
+   * - `urn:ietf:params:oauth:token-type:saml2` - For SAML 2.0 assertions
+   *
+   * For custom/legacy tokens, use organization-controlled URIs. Forbidden patterns for custom types:
+   * - `urn:ietf:params:oauth:*` (IETF reserved for standard types only)
    * - `https://auth0.com/*` (Auth0 reserved)
    * - `urn:auth0:*` (Auth0 reserved)
    *
-   * @example "urn:acme:legacy-system-token"
+   * @example "urn:acme:legacy-system-token" // Custom legacy token
+   * @example "urn:ietf:params:oauth:token-type:jwt" // Standard JWT from OIDC provider
    */
   subjectTokenType: string;
 

From 5f3045655931d81946992be8eacc55fdd2c6e2ff Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Tue, 20 Jan 2026 12:54:27 +0530
Subject: [PATCH 5/8] feat: remove AuthenticationException and related tests,
 refactor error handling in NativeBridgeManager and WebAuth0Client

---
 src/core/models/AuthenticationException.ts    | 233 ------------------
 .../__tests__/AuthenticationException.spec.ts | 199 ---------------
 src/core/models/index.ts                      |   4 -
 src/index.ts                                  |   2 -
 .../native/bridge/NativeBridgeManager.ts      |  17 +-
 .../__tests__/NativeBridgeManager.spec.ts     |  47 +---
 src/platforms/web/adapters/WebAuth0Client.ts  |   9 +-
 7 files changed, 12 insertions(+), 499 deletions(-)
 delete mode 100644 src/core/models/AuthenticationException.ts
 delete mode 100644 src/core/models/__tests__/AuthenticationException.spec.ts

diff --git a/src/core/models/AuthenticationException.ts b/src/core/models/AuthenticationException.ts
deleted file mode 100644
index a256cc39..00000000
--- a/src/core/models/AuthenticationException.ts
+++ /dev/null
@@ -1,233 +0,0 @@
-import { AuthError } from './AuthError';
-
-/**
- * Platform-agnostic error code constants for Authentication API operations.
- *
- * Use these constants for type-safe error handling when working with authentication operations.
- * Each constant corresponds to a specific error type in the {@link AuthenticationException.type} property.
- *
- * @example
- * ```typescript
- * import { AuthenticationException, AuthenticationErrorCodes } from 'react-native-auth0';
- *
- * try {
- *   const credentials = await auth0.auth.login({
- *     username: 'user@example.com',
- *     password: 'password',
- *   });
- * } catch (e) {
- *   if (e instanceof AuthenticationException) {
- *     switch (e.type) {
- *       case AuthenticationErrorCodes.INVALID_CREDENTIALS:
- *         // Invalid username or password
- *         break;
- *       case AuthenticationErrorCodes.INVALID_GRANT:
- *         // Token or grant is invalid
- *         break;
- *       case AuthenticationErrorCodes.PASSWORD_LEAKED:
- *         // Password was found in a data breach
- *         break;
- *     }
- *   }
- * }
- * ```
- *
- * @see {@link AuthenticationException}
- * @see {@link https://auth0.com/docs/api/authentication|Authentication API}
- */
-export const AuthenticationErrorCodes = {
-  // General authentication errors
-  /** Invalid credentials provided (username/password/code/token) */
-  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
-  /** Invalid or expired grant/token */
-  INVALID_GRANT: 'INVALID_GRANT',
-  /** Invalid request parameters */
-  INVALID_REQUEST: 'INVALID_REQUEST',
-  /** Access denied by authorization server or Actions/Rules */
-  ACCESS_DENIED: 'ACCESS_DENIED',
-  /** Unauthorized client */
-  UNAUTHORIZED_CLIENT: 'UNAUTHORIZED_CLIENT',
-
-  // Password-related errors
-  /** Password does not meet strength requirements */
-  PASSWORD_STRENGTH: 'PASSWORD_STRENGTH',
-  /** Password was previously used */
-  PASSWORD_ALREADY_USED: 'PASSWORD_ALREADY_USED',
-  /** Password was found in a data breach */
-  PASSWORD_LEAKED: 'PASSWORD_LEAKED',
-
-  // MFA-related errors
-  /** MFA is required */
-  MFA_REQUIRED: 'MFA_REQUIRED',
-  /** Invalid MFA code */
-  MFA_INVALID_CODE: 'MFA_INVALID_CODE',
-  /** MFA token is invalid or expired */
-  MFA_TOKEN_INVALID: 'MFA_TOKEN_INVALID',
-
-  // Token Exchange specific errors
-  /** The subject token is invalid, malformed, or expired */
-  INVALID_SUBJECT_TOKEN: 'INVALID_SUBJECT_TOKEN',
-  /** The subject token type is not supported or not recognized */
-  UNSUPPORTED_TOKEN_TYPE: 'UNSUPPORTED_TOKEN_TYPE',
-  /** Custom Token Exchange is not configured or enabled */
-  TOKEN_EXCHANGE_NOT_CONFIGURED: 'TOKEN_EXCHANGE_NOT_CONFIGURED',
-  /** Token validation in Auth0 Action failed */
-  TOKEN_VALIDATION_FAILED: 'TOKEN_VALIDATION_FAILED',
-  /** Token exchange request was denied */
-  TOKEN_EXCHANGE_DENIED: 'TOKEN_EXCHANGE_DENIED',
-
-  // Scope and audience errors
-  /** The requested audience is invalid or not allowed */
-  INVALID_AUDIENCE: 'INVALID_AUDIENCE',
-  /** The requested scope is invalid or not allowed */
-  INVALID_SCOPE: 'INVALID_SCOPE',
-
-  // Rate limiting and security
-  /** Too many authentication attempts */
-  TOO_MANY_ATTEMPTS: 'TOO_MANY_ATTEMPTS',
-  /** Additional verification is required */
-  VERIFICATION_REQUIRED: 'VERIFICATION_REQUIRED',
-  /** Login is required (for silent authentication) */
-  LOGIN_REQUIRED: 'LOGIN_REQUIRED',
-
-  // Network and server errors
-  /** Network error occurred */
-  NETWORK_ERROR: 'NETWORK_ERROR',
-  /** The authorization server encountered an internal error */
-  SERVER_ERROR: 'SERVER_ERROR',
-
-  /** Unknown or uncategorized authentication error */
-  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
-} as const;
-
-/**
- * Type for the values of AuthenticationErrorCodes.
- */
-export type AuthenticationErrorCode =
-  (typeof AuthenticationErrorCodes)[keyof typeof AuthenticationErrorCodes];
-
-const ERROR_CODE_MAP: Record<string, AuthenticationErrorCode> = {
-  // OAuth 2.0 / RFC 6749 standard error codes
-  'invalid_request': AuthenticationErrorCodes.INVALID_REQUEST,
-  'invalid_grant': AuthenticationErrorCodes.INVALID_GRANT,
-  'invalid_token': AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
-  'invalid_client': AuthenticationErrorCodes.INVALID_CREDENTIALS,
-  'invalid_credentials': AuthenticationErrorCodes.INVALID_CREDENTIALS,
-  'unauthorized_client': AuthenticationErrorCodes.UNAUTHORIZED_CLIENT,
-  'unsupported_grant_type': AuthenticationErrorCodes.INVALID_REQUEST,
-  'invalid_scope': AuthenticationErrorCodes.INVALID_SCOPE,
-  'access_denied': AuthenticationErrorCodes.ACCESS_DENIED,
-  'server_error': AuthenticationErrorCodes.SERVER_ERROR,
-
-  // RFC 8693 Token Exchange specific
-  'unsupported_token_type': AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE,
-  'invalid_target': AuthenticationErrorCodes.INVALID_AUDIENCE,
-
-  // Auth0-specific error codes - General
-  'unauthorized': AuthenticationErrorCodes.ACCESS_DENIED,
-
-  // Auth0-specific error codes - MFA
-  'a0.mfa_required': AuthenticationErrorCodes.MFA_REQUIRED,
-  'a0.mfa_invalid_code': AuthenticationErrorCodes.MFA_INVALID_CODE,
-  'a0.mfa_token_invalid': AuthenticationErrorCodes.MFA_TOKEN_INVALID,
-  'mfa_required': AuthenticationErrorCodes.MFA_REQUIRED,
-  'mfa_token_invalid': AuthenticationErrorCodes.MFA_TOKEN_INVALID,
-  'expired_token': AuthenticationErrorCodes.MFA_TOKEN_INVALID,
-
-  // Auth0-specific error codes - Password
-  'invalid_password': AuthenticationErrorCodes.INVALID_CREDENTIALS,
-  'password_leaked': AuthenticationErrorCodes.PASSWORD_LEAKED,
-  'password_strength_error': AuthenticationErrorCodes.PASSWORD_STRENGTH,
-  'password_history_error': AuthenticationErrorCodes.PASSWORD_ALREADY_USED,
-  'password_already_used': AuthenticationErrorCodes.PASSWORD_ALREADY_USED,
-
-  // Auth0-specific error codes - Rate Limiting & Verification
-  'too_many_attempts': AuthenticationErrorCodes.TOO_MANY_ATTEMPTS,
-  'requires_verification': AuthenticationErrorCodes.VERIFICATION_REQUIRED,
-  'verification_required': AuthenticationErrorCodes.VERIFICATION_REQUIRED,
-  'login_required': AuthenticationErrorCodes.LOGIN_REQUIRED,
-
-  // Token Exchange specific Auth0 codes
-  'a0.token_exchange_failed': AuthenticationErrorCodes.TOKEN_EXCHANGE_DENIED,
-  'a0.token_exchange_not_enabled':
-    AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-  'a0.invalid_subject_token': AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
-  'a0.subject_token_expired': AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
-  'a0.subject_token_validation_failed':
-    AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED,
-  'a0.action_failed': AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED,
-
-  // Network errors
-  'a0.network_error': AuthenticationErrorCodes.NETWORK_ERROR,
-};
-
-/**
- * Represents an error that occurred during an Authentication API operation.
- *
- * This error class provides structured error handling for authentication operations,
- * with platform-agnostic error codes that normalize errors from iOS, Android, and web platforms.
- *
- * The Authentication API handles various operations including:
- * - Login (username/password, passwordless, social)
- * - Token exchange and refresh
- * - Multi-factor authentication
- * - Password management
- *
- * The `type` property provides a normalized, platform-agnostic error code that
- * applications can use for consistent error handling across iOS, Android, and Web.
- *
- * @example
- * ```typescript
- * import {
- *   AuthenticationException,
- *   AuthenticationErrorCodes
- * } from 'react-native-auth0';
- *
- * try {
- *   const credentials = await auth0.auth.login({
- *     username: 'user@example.com',
- *     password: 'password',
- *     realm: 'Username-Password-Authentication',
- *   });
- * } catch (e) {
- *   if (e instanceof AuthenticationException) {
- *     console.log('Error type:', e.type);
- *     console.log('Error message:', e.message);
- *
- *     if (e.type === AuthenticationErrorCodes.INVALID_CREDENTIALS) {
- *       // Invalid username or password
- *     } else if (e.type === AuthenticationErrorCodes.PASSWORD_LEAKED) {
- *       // Password found in breach database
- *     }
- *   }
- * }
- * ```
- *
- * @see {@link AuthenticationErrorCodes}
- * @see {@link https://auth0.com/docs/api/authentication|Authentication API}
- */
-export class AuthenticationException extends AuthError {
-  /**
-   * A normalized error type that is consistent across platforms.
-   * This can be used for reliable error handling in application code.
-   */
-  public readonly type: AuthenticationErrorCode;
-
-  /**
-   * Constructs a new AuthenticationException instance from an AuthError.
-   *
-   * @param originalError The original AuthError that occurred during an authentication operation.
-   */
-  constructor(originalError: AuthError) {
-    super(originalError.name, originalError.message, {
-      status: originalError.status,
-      code: originalError.code,
-      json: originalError.json,
-    });
-
-    // Map the original error code to a normalized type
-    this.type =
-      ERROR_CODE_MAP[originalError.code] ||
-      AuthenticationErrorCodes.UNKNOWN_ERROR;
-  }
-}
diff --git a/src/core/models/__tests__/AuthenticationException.spec.ts b/src/core/models/__tests__/AuthenticationException.spec.ts
deleted file mode 100644
index 5bf6d627..00000000
--- a/src/core/models/__tests__/AuthenticationException.spec.ts
+++ /dev/null
@@ -1,199 +0,0 @@
-import {
-  AuthenticationException,
-  AuthenticationErrorCodes,
-} from '../AuthenticationException';
-import { AuthError } from '../AuthError';
-
-describe('AuthenticationException', () => {
-  describe('constructor', () => {
-    it('should create error with correct name', () => {
-      const authError = new AuthError('invalid_grant', 'Token expired', {
-        code: 'invalid_grant',
-      });
-      const error = new AuthenticationException(authError);
-
-      expect(error.name).toBe('invalid_grant');
-    });
-
-    it('should preserve the error message', () => {
-      const authError = new AuthError('invalid_grant', 'Token expired', {
-        code: 'invalid_grant',
-      });
-      const error = new AuthenticationException(authError);
-
-      expect(error.message).toBe('Token expired');
-    });
-
-    it('should preserve the error code', () => {
-      const authError = new AuthError('invalid_grant', 'Token expired', {
-        code: 'invalid_grant',
-      });
-      const error = new AuthenticationException(authError);
-
-      expect(error.code).toBe('invalid_grant');
-    });
-  });
-
-  describe('error code mapping', () => {
-    it.each([
-      // OAuth 2.0 / RFC 6749 error codes - General auth errors
-      ['invalid_request', AuthenticationErrorCodes.INVALID_REQUEST],
-      ['invalid_grant', AuthenticationErrorCodes.INVALID_GRANT],
-      ['invalid_credentials', AuthenticationErrorCodes.INVALID_CREDENTIALS],
-      ['access_denied', AuthenticationErrorCodes.ACCESS_DENIED],
-      ['unauthorized_client', AuthenticationErrorCodes.UNAUTHORIZED_CLIENT],
-      ['invalid_scope', AuthenticationErrorCodes.INVALID_SCOPE],
-      ['invalid_token', AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN],
-
-      // Token exchange specific errors
-      ['server_error', AuthenticationErrorCodes.SERVER_ERROR],
-      [
-        'a0.token_exchange_failed',
-        AuthenticationErrorCodes.TOKEN_EXCHANGE_DENIED,
-      ],
-      [
-        'a0.token_exchange_not_enabled',
-        AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-      ],
-      [
-        'unsupported_token_type',
-        AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE,
-      ],
-      ['invalid_target', AuthenticationErrorCodes.INVALID_AUDIENCE],
-      [
-        'a0.invalid_subject_token',
-        AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
-      ],
-      [
-        'a0.subject_token_expired',
-        AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN,
-      ],
-      [
-        'a0.subject_token_validation_failed',
-        AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED,
-      ],
-      ['a0.action_failed', AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED],
-
-      // Password errors
-      ['password_strength_error', AuthenticationErrorCodes.PASSWORD_STRENGTH],
-      ['password_leaked', AuthenticationErrorCodes.PASSWORD_LEAKED],
-      ['password_already_used', AuthenticationErrorCodes.PASSWORD_ALREADY_USED],
-
-      // MFA errors
-      ['a0.mfa_required', AuthenticationErrorCodes.MFA_REQUIRED],
-      ['mfa_required', AuthenticationErrorCodes.MFA_REQUIRED],
-      ['a0.mfa_invalid_code', AuthenticationErrorCodes.MFA_INVALID_CODE],
-      ['a0.mfa_token_invalid', AuthenticationErrorCodes.MFA_TOKEN_INVALID],
-
-      // Rate limiting and verification
-      ['too_many_attempts', AuthenticationErrorCodes.TOO_MANY_ATTEMPTS],
-      ['verification_required', AuthenticationErrorCodes.VERIFICATION_REQUIRED],
-      ['login_required', AuthenticationErrorCodes.LOGIN_REQUIRED],
-
-      // Network errors
-      ['a0.network_error', AuthenticationErrorCodes.NETWORK_ERROR],
-    ])('should map "%s" to %s', (errorCode, expectedType) => {
-      const authError = new AuthError(errorCode, 'Test error', {
-        code: errorCode,
-      });
-      const error = new AuthenticationException(authError);
-
-      expect(error.type).toBe(expectedType);
-    });
-
-    it('should map unknown error codes to UNKNOWN_ERROR', () => {
-      const authError = new AuthError('some_unknown_code', 'Unknown error', {
-        code: 'some_unknown_code',
-      });
-      const error = new AuthenticationException(authError);
-
-      expect(error.type).toBe(AuthenticationErrorCodes.UNKNOWN_ERROR);
-    });
-
-    it('should use default code when code is not explicitly provided', () => {
-      // When code is not provided in details, AuthError defaults to 'unknown_error'
-      const authError = new AuthError('invalid_grant', 'Test error');
-      const error = new AuthenticationException(authError);
-
-      // Since code defaults to 'unknown_error', it maps to UNKNOWN_ERROR
-      expect(error.type).toBe(AuthenticationErrorCodes.UNKNOWN_ERROR);
-    });
-
-    it('should prefer explicit code over name when mapping error type', () => {
-      const authError = new AuthError('some_name', 'Test error', {
-        code: 'invalid_grant',
-      });
-      const error = new AuthenticationException(authError);
-
-      expect(error.type).toBe(AuthenticationErrorCodes.INVALID_GRANT);
-    });
-  });
-
-  describe('AuthenticationErrorCodes', () => {
-    it('should export all expected error codes', () => {
-      // General auth errors
-      expect(AuthenticationErrorCodes.INVALID_REQUEST).toBe('INVALID_REQUEST');
-      expect(AuthenticationErrorCodes.INVALID_GRANT).toBe('INVALID_GRANT');
-      expect(AuthenticationErrorCodes.INVALID_CREDENTIALS).toBe(
-        'INVALID_CREDENTIALS'
-      );
-      expect(AuthenticationErrorCodes.ACCESS_DENIED).toBe('ACCESS_DENIED');
-      expect(AuthenticationErrorCodes.UNAUTHORIZED_CLIENT).toBe(
-        'UNAUTHORIZED_CLIENT'
-      );
-
-      // Token exchange errors
-      expect(AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN).toBe(
-        'INVALID_SUBJECT_TOKEN'
-      );
-      expect(AuthenticationErrorCodes.UNSUPPORTED_TOKEN_TYPE).toBe(
-        'UNSUPPORTED_TOKEN_TYPE'
-      );
-      expect(AuthenticationErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED).toBe(
-        'TOKEN_EXCHANGE_NOT_CONFIGURED'
-      );
-      expect(AuthenticationErrorCodes.INVALID_AUDIENCE).toBe(
-        'INVALID_AUDIENCE'
-      );
-      expect(AuthenticationErrorCodes.INVALID_SCOPE).toBe('INVALID_SCOPE');
-      expect(AuthenticationErrorCodes.TOKEN_EXCHANGE_DENIED).toBe(
-        'TOKEN_EXCHANGE_DENIED'
-      );
-      expect(AuthenticationErrorCodes.TOKEN_VALIDATION_FAILED).toBe(
-        'TOKEN_VALIDATION_FAILED'
-      );
-
-      // Password errors
-      expect(AuthenticationErrorCodes.PASSWORD_STRENGTH).toBe(
-        'PASSWORD_STRENGTH'
-      );
-      expect(AuthenticationErrorCodes.PASSWORD_LEAKED).toBe('PASSWORD_LEAKED');
-      expect(AuthenticationErrorCodes.PASSWORD_ALREADY_USED).toBe(
-        'PASSWORD_ALREADY_USED'
-      );
-
-      // MFA errors
-      expect(AuthenticationErrorCodes.MFA_REQUIRED).toBe('MFA_REQUIRED');
-      expect(AuthenticationErrorCodes.MFA_INVALID_CODE).toBe(
-        'MFA_INVALID_CODE'
-      );
-      expect(AuthenticationErrorCodes.MFA_TOKEN_INVALID).toBe(
-        'MFA_TOKEN_INVALID'
-      );
-
-      // Rate limiting
-      expect(AuthenticationErrorCodes.TOO_MANY_ATTEMPTS).toBe(
-        'TOO_MANY_ATTEMPTS'
-      );
-      expect(AuthenticationErrorCodes.VERIFICATION_REQUIRED).toBe(
-        'VERIFICATION_REQUIRED'
-      );
-      expect(AuthenticationErrorCodes.LOGIN_REQUIRED).toBe('LOGIN_REQUIRED');
-
-      // Common errors
-      expect(AuthenticationErrorCodes.NETWORK_ERROR).toBe('NETWORK_ERROR');
-      expect(AuthenticationErrorCodes.SERVER_ERROR).toBe('SERVER_ERROR');
-      expect(AuthenticationErrorCodes.UNKNOWN_ERROR).toBe('UNKNOWN_ERROR');
-    });
-  });
-});
diff --git a/src/core/models/index.ts b/src/core/models/index.ts
index 6da94065..d6d3857b 100644
--- a/src/core/models/index.ts
+++ b/src/core/models/index.ts
@@ -8,7 +8,3 @@ export {
 } from './CredentialsManagerError';
 export { WebAuthError, WebAuthErrorCodes } from './WebAuthError';
 export { DPoPError, DPoPErrorCodes } from './DPoPError';
-export {
-  AuthenticationException,
-  AuthenticationErrorCodes,
-} from './AuthenticationException';
diff --git a/src/index.ts b/src/index.ts
index 13c0ba3c..28339a14 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,8 +6,6 @@ export {
   WebAuthErrorCodes,
   DPoPError,
   DPoPErrorCodes,
-  AuthenticationException,
-  AuthenticationErrorCodes,
 } from './core/models';
 export { TimeoutError } from './core/utils/fetchWithTimeout';
 export { TokenType } from './types/common';
diff --git a/src/platforms/native/bridge/NativeBridgeManager.ts b/src/platforms/native/bridge/NativeBridgeManager.ts
index f3151b21..a5e3a6b7 100644
--- a/src/platforms/native/bridge/NativeBridgeManager.ts
+++ b/src/platforms/native/bridge/NativeBridgeManager.ts
@@ -16,7 +16,6 @@ import {
 import {
   AuthError,
   Credentials as CredentialsModel,
-  AuthenticationException,
 } from '../../../core/models';
 import Auth0NativeModule from '../../../specs/NativeA0Auth0';
 import type { NativeModuleError } from '../../../core/interfaces';
@@ -244,16 +243,12 @@ export class NativeBridgeManager implements INativeBridge {
       );
       return new CredentialsModel(credential);
     } catch (e) {
-      // Wrap AuthError in AuthenticationException for better error handling
-      const authError =
-        e instanceof AuthError
-          ? e
-          : new AuthError(
-              'authentication_error',
-              e instanceof Error ? e.message : String(e),
-              { code: 'authentication_error', json: e }
-            );
-      throw new AuthenticationException(authError);
+      // Convert to AuthError if needed, then throw directly
+      throw new AuthError(
+        e instanceof AuthError ? e.code : 'custom_token_exchange_failed',
+        e instanceof Error ? e.message : String(e),
+        { code: 'custom_token_exchange_failed', json: e }
+      );
     }
   }
 }
diff --git a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
index 1dc89dd7..2950897c 100644
--- a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
+++ b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
@@ -1,9 +1,5 @@
 import { NativeBridgeManager } from '../NativeBridgeManager';
-import {
-  AuthError,
-  Credentials,
-  AuthenticationException,
-} from '../../../../core/models';
+import { AuthError, Credentials } from '../../../../core/models';
 import Auth0NativeModule from '../../../../specs/NativeA0Auth0';
 
 // Mock the entire spec file, which is our native module.
@@ -268,7 +264,7 @@ describe('NativeBridgeManager', () => {
       expect(credentials.tokenType).toBe('Bearer');
     });
 
-    it('should throw AuthenticationException when native method fails', async () => {
+    it('should throw AuthError when native method fails', async () => {
       const nativeError = {
         code: 'a0.token_exchange_failed',
         message: 'Token exchange failed',
@@ -279,50 +275,15 @@ describe('NativeBridgeManager', () => {
 
       await expect(
         bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token')
-      ).rejects.toThrow(AuthenticationException);
+      ).rejects.toThrow(AuthError);
 
       try {
         await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
       } catch (e) {
-        const tokenExchangeError = e as AuthenticationException;
-        expect(tokenExchangeError.type).toBe('TOKEN_EXCHANGE_DENIED');
+        const tokenExchangeError = e as AuthError;
         expect(tokenExchangeError.message).toBe('Token exchange failed');
         expect(tokenExchangeError.code).toBe('a0.token_exchange_failed');
       }
     });
-
-    it('should map invalid_grant error to INVALID_GRANT type', async () => {
-      const nativeError = {
-        code: 'invalid_grant',
-        message: 'The subject token is invalid',
-      };
-      MockedAuth0NativeModule.customTokenExchange.mockRejectedValue(
-        nativeError
-      );
-
-      try {
-        await bridge.customTokenExchange('bad-token', 'urn:acme:legacy-token');
-      } catch (e) {
-        const tokenExchangeError = e as AuthenticationException;
-        expect(tokenExchangeError.type).toBe('INVALID_GRANT');
-      }
-    });
-
-    it('should map unsupported_token_type error correctly', async () => {
-      const nativeError = {
-        code: 'unsupported_token_type',
-        message: 'The token type is not supported',
-      };
-      MockedAuth0NativeModule.customTokenExchange.mockRejectedValue(
-        nativeError
-      );
-
-      try {
-        await bridge.customTokenExchange('token', 'urn:unknown:type');
-      } catch (e) {
-        const tokenExchangeError = e as AuthenticationException;
-        expect(tokenExchangeError.type).toBe('UNSUPPORTED_TOKEN_TYPE');
-      }
-    });
   });
 });
diff --git a/src/platforms/web/adapters/WebAuth0Client.ts b/src/platforms/web/adapters/WebAuth0Client.ts
index 467c578c..b64240dd 100644
--- a/src/platforms/web/adapters/WebAuth0Client.ts
+++ b/src/platforms/web/adapters/WebAuth0Client.ts
@@ -22,11 +22,7 @@ import {
 } from '../../../core/services';
 import { HttpClient } from '../../../core/services/HttpClient';
 import { TokenType } from '../../../types/common';
-import {
-  AuthError,
-  DPoPError,
-  AuthenticationException,
-} from '../../../core/models';
+import { AuthError, DPoPError } from '../../../core/models';
 
 export class WebAuth0Client implements IAuth0Client {
   readonly webAuth: WebWebAuthProvider;
@@ -248,12 +244,11 @@ export class WebAuth0Client implements IAuth0Client {
         refreshToken: response.refresh_token,
       };
     } catch (e: any) {
-      const authError = new AuthError(
+      throw new AuthError(
         e.error ?? 'custom_token_exchange_failed',
         e.error_description ?? e.message ?? 'Custom token exchange failed',
         { json: e }
       );
-      throw new AuthenticationException(authError);
     }
   }
 }

From 9e59c95994ceff837779c0096bccca1125462afe Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Tue, 20 Jan 2026 13:23:12 +0530
Subject: [PATCH 6/8] feat: refactor custom token exchange to use request
 builder for audience and scope

---
 .../src/main/java/com/auth0/react/A0Auth0Module.kt | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/android/src/main/java/com/auth0/react/A0Auth0Module.kt b/android/src/main/java/com/auth0/react/A0Auth0Module.kt
index 05ef15df..ade908c0 100644
--- a/android/src/main/java/com/auth0/react/A0Auth0Module.kt
+++ b/android/src/main/java/com/auth0/react/A0Auth0Module.kt
@@ -485,13 +485,17 @@ class A0Auth0Module(private val reactContext: ReactApplicationContext) : A0Auth0
         
         val finalScope = scope ?: "openid profile email"
         
-        authClient.customTokenExchange(
-            subjectToken = subjectToken,
+        val request = authClient.customTokenExchange(
             subjectTokenType = subjectTokenType,
-            audience = audience,
-            scope = finalScope,
+            subjectToken = subjectToken,
             organization = organization
-        ).start(object : com.auth0.android.callback.Callback<Credentials, AuthenticationException> {
+        )
+        
+        // Set audience and scope using the request builder methods
+        audience?.let { request.setAudience(it) }
+        request.setScope(finalScope)
+        
+        request.start(object : com.auth0.android.callback.Callback<Credentials, AuthenticationException> {
             override fun onSuccess(result: Credentials) {
                 val map = CredentialsParser.toMap(result)
                 promise.resolve(map)

From b52defa7ad71d46cd2907a219367fa86100b157a Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Wed, 21 Jan 2026 13:28:59 +0530
Subject: [PATCH 7/8] fix: update error code for token exchange failure in
 NativeBridgeManager tests

---
 .../native/bridge/__tests__/NativeBridgeManager.spec.ts         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
index 2950897c..aadec133 100644
--- a/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
+++ b/src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
@@ -282,7 +282,7 @@ describe('NativeBridgeManager', () => {
       } catch (e) {
         const tokenExchangeError = e as AuthError;
         expect(tokenExchangeError.message).toBe('Token exchange failed');
-        expect(tokenExchangeError.code).toBe('a0.token_exchange_failed');
+        expect(tokenExchangeError.code).toBe('custom_token_exchange_failed');
       }
     });
   });

From 2af5930b0b2723acaeb1de94fda1101b009a8e01 Mon Sep 17 00:00:00 2001
From: Subhankar Maiti <subhankar.maiti@okta.com>
Date: Wed, 21 Jan 2026 15:28:26 +0530
Subject: [PATCH 8/8] update custom token exchange documentation and parameters
 for clarity and compliance

---
 EXAMPLES.md                                   | 112 ++++++----
 src/Auth0.ts                                  |   2 +-
 src/core/models/CustomTokenExchangeError.ts   | 201 ------------------
 .../CustomTokenExchangeError.spec.ts          | 193 -----------------
 src/types/parameters.ts                       |  22 +-
 5 files changed, 77 insertions(+), 453 deletions(-)
 delete mode 100644 src/core/models/CustomTokenExchangeError.ts
 delete mode 100644 src/core/models/__tests__/CustomTokenExchangeError.spec.ts

diff --git a/EXAMPLES.md b/EXAMPLES.md
index 391d2c7d..638e94c8 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -885,36 +885,38 @@ const credentials = await customTokenExchange({
 
 ### Subject Token Type Requirements
 
-The `subjectTokenType` parameter identifies the type of token being exchanged. Choose the appropriate type based on your use case:
+The `subjectTokenType` parameter must be a **unique profile token type URI** starting with `https://` or `urn:`.
 
-#### For Standard OAuth Tokens (RFC 8693)
+#### Valid Token Type Patterns
 
-When exchanging tokens from standard OAuth/OIDC providers (e.g., another Auth0 tenant, external IdP using standard protocols), use RFC 8693 standard token types:
+You control the token type namespace. Use one of these patterns:
 
-- `urn:ietf:params:oauth:token-type:jwt` - For JWTs (e.g., ID tokens, signed access tokens)
-- `urn:ietf:params:oauth:token-type:access_token` - For OAuth access tokens
-- `urn:ietf:params:oauth:token-type:refresh_token` - For OAuth refresh tokens
-- `urn:ietf:params:oauth:token-type:id_token` - For OIDC ID tokens
-- `urn:ietf:params:oauth:token-type:saml1` - For SAML 1.1 assertions
-- `urn:ietf:params:oauth:token-type:saml2` - For SAML 2.0 assertions
+**URN Format (Recommended):**
 
-#### For Custom/Legacy Tokens
+- `urn:yourcompany:token-type` - Company-specific token type
+- `urn:acme:legacy-system-token` - Legacy system tokens
+- `urn:example:external-idp` - External IdP tokens
 
-When exchanging tokens from custom systems or legacy identity providers that don't use standard OAuth formats, you MUST use organization-controlled URIs. The following patterns are **forbidden** for custom tokens:
+**HTTPS URL Format:**
 
-- `urn:ietf:params:oauth:*` (IETF reserved for RFC 8693 standard types only)
-- `https://auth0.com/*` (Auth0 reserved)
-- `urn:auth0:*` (Auth0 reserved)
+- `https://yourcompany.com/tokens/legacy` - Using your organization's domain
+- `https://example.com/custom-token` - Custom token identifier
 
-**Valid custom token type examples:**
+#### Reserved Namespaces (Forbidden)
 
-- `urn:acme:legacy-system-token` - For proprietary legacy system tokens
-- `urn:yourcompany:external-idp` - For external IdP tokens
-- `https://yourcompany.com/tokens/legacy` - Using your organization's domain
+The following namespaces are **reserved** and you **CANNOT use them**:
+
+- ❌ `http://auth0.com/*`
+- ❌ `https://auth0.com/*`
+- ❌ `http://okta.com/*`
+- ❌ `https://okta.com/*`
+- ❌ `urn:ietf:*`
+- ❌ `urn:auth0:*`
+- ❌ `urn:okta:*`
 
 #### Common Use Cases
 
-1. **Seamless Migration from Legacy IdP**: Exchange legacy refresh tokens using a custom type
+1. **Seamless Migration from Legacy IdP**: Exchange legacy refresh tokens
 
    ```typescript
    await customTokenExchange({
@@ -924,47 +926,65 @@ When exchanging tokens from custom systems or legacy identity providers that don
    });
    ```
 
-2. **Re-use External Authentication**: Exchange ID token from external provider
+2. **External Authentication Provider**: Exchange tokens from partner IdP
 
    ```typescript
    await customTokenExchange({
-     subjectToken: externalIdToken,
-     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt', // Standard JWT
+     subjectToken: externalProviderToken,
+     subjectTokenType: 'urn:partner:auth-token',
      scope: 'openid profile email',
    });
    ```
 
-3. **Service-to-Service Token Exchange**: Exchange Auth0 access token for different audience
+3. **Custom JWT Tokens**: Exchange JWTs from your own system
    ```typescript
    await customTokenExchange({
-     subjectToken: currentAccessToken,
-     subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
-     audience: 'https://api-b.example.com',
+     subjectToken: customJwt,
+     subjectTokenType: 'urn:yourcompany:jwt-token',
+     audience: 'https://api.example.com',
    });
    ```
 
 ### Error Codes Reference
 
-The `CustomTokenExchangeError` class provides platform-agnostic error codes that are mapped from the underlying native SDK errors. Use the `type` property for programmatic error handling:
-
-| Error Code                      | Description                                                |
-| ------------------------------- | ---------------------------------------------------------- |
-| `INVALID_SUBJECT_TOKEN`         | The external token is invalid, malformed, or expired       |
-| `UNSUPPORTED_TOKEN_TYPE`        | The token type is not supported or recognized              |
-| `TOKEN_EXCHANGE_NOT_CONFIGURED` | Custom Token Exchange is not enabled for this Auth0 tenant |
-| `INVALID_AUDIENCE`              | The requested audience is invalid or not allowed           |
-| `INVALID_SCOPE`                 | The requested scope is invalid or not allowed              |
-| `TOKEN_EXCHANGE_DENIED`         | Token exchange was denied by the authorization server      |
-| `TOKEN_VALIDATION_FAILED`       | The token validation in Auth0 Action failed                |
-| `NETWORK_ERROR`                 | Network connectivity issue occurred                        |
-| `SERVER_ERROR`                  | The authorization server encountered an internal error     |
-| `UNKNOWN_ERROR`                 | An unknown or uncategorized error occurred                 |
-
-These error codes are mapped from:
-
-- **RFC 8693 standard errors**: `invalid_grant`, `invalid_request`, `unsupported_token_type`, `access_denied`, etc.
-- **Auth0-specific errors**: `a0.token_exchange_failed`, `a0.action_failed`, etc.
-- **Native SDK errors**: Platform-specific error codes from Auth0.swift and Auth0.Android
+Custom Token Exchange throws `AuthError` with specific error codes for different failure scenarios. Use the `code` property for programmatic error handling:
+
+```typescript
+try {
+  await auth0.customTokenExchange({...});
+} catch (error) {
+  console.error('Error code:', error.code);
+  console.error('Error message:', error.message);
+
+  // Handle specific errors
+  if (error.code === 'invalid_grant') {
+    // Handle invalid token
+  }
+}
+```
+
+| Error Code                          | Description                                                |
+| ----------------------------------- | ---------------------------------------------------------- |
+| `custom_token_exchange_failed`      | General token exchange failure                             |
+| `invalid_grant`                     | The external token is invalid, malformed, or expired       |
+| `invalid_request`                   | The request is missing required parameters or is malformed |
+| `unsupported_token_type`            | The token type is not supported or recognized              |
+| `unauthorized_client`               | Custom Token Exchange is not enabled for this client       |
+| `invalid_target`                    | The requested audience is invalid or not allowed           |
+| `invalid_scope`                     | The requested scope is invalid or not allowed              |
+| `access_denied`                     | Token exchange was denied by the authorization server      |
+| `server_error`                      | The authorization server encountered an internal error     |
+| `temporarily_unavailable`           | The server is temporarily unable to handle the request     |
+| `network_error`                     | Network connectivity issue occurred                        |
+| `a0.token_exchange_failed`          | Auth0-specific token exchange failure                      |
+| `a0.action_failed`                  | The token validation in Auth0 Action failed                |
+| `a0.invalid_subject_token`          | Subject token validation failed                            |
+| `a0.unsupported_subject_token_type` | Subject token type is not supported                        |
+
+These error codes follow:
+
+- **RFC 8693 standard**: `invalid_grant`, `invalid_request`, `unsupported_token_type`, `access_denied`, etc.
+- **Auth0-specific codes**: `a0.token_exchange_failed`, `a0.action_failed`, etc.
 
 ### Auth0 Actions Validation
 
diff --git a/src/Auth0.ts b/src/Auth0.ts
index 7bdf9ac2..d01ec99b 100644
--- a/src/Auth0.ts
+++ b/src/Auth0.ts
@@ -109,7 +109,7 @@ class Auth0 {
    * ```typescript
    * const credentials = await auth0.customTokenExchange({
    *   subjectToken: 'external-idp-token',
-   *   subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
+   *   subjectTokenType: 'urn:acme:external-idp-token',
    *   audience: 'https://api.example.com',
    *   scope: 'openid profile email',
    *   organization: 'org_abc123'
diff --git a/src/core/models/CustomTokenExchangeError.ts b/src/core/models/CustomTokenExchangeError.ts
deleted file mode 100644
index 4fef0965..00000000
--- a/src/core/models/CustomTokenExchangeError.ts
+++ /dev/null
@@ -1,201 +0,0 @@
-import { AuthError } from './AuthError';
-
-/**
- * Platform-agnostic error code constants for Custom Token Exchange operations.
- *
- * Use these constants for type-safe error handling when working with token exchange.
- * Each constant corresponds to a specific error type in the {@link CustomTokenExchangeError.type} property.
- *
- * @example
- * ```typescript
- * import { CustomTokenExchangeError, CustomTokenExchangeErrorCodes } from 'react-native-auth0';
- *
- * try {
- *   // Exchange a custom legacy token
- *   const credentials = await auth0.customTokenExchange({
- *     subjectToken: externalToken,
- *     subjectTokenType: 'urn:acme:legacy-system-token',
- *   });
- * } catch (e) {
- *   if (e instanceof CustomTokenExchangeError) {
- *     switch (e.type) {
- *       case CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN:
- *         // The external token is invalid or expired
- *         break;
- *       case CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE:
- *         // The token type is not supported
- *         break;
- *       case CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED:
- *         // Custom Token Exchange is not configured in Auth0
- *         break;
- *     }
- *   }
- * }
- * ```
- *
- * @see {@link CustomTokenExchangeError}
- * @see {@link https://datatracker.ietf.org/doc/html/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
- */
-export const CustomTokenExchangeErrorCodes = {
-  /** The subject token is invalid, malformed, or expired */
-  INVALID_SUBJECT_TOKEN: 'INVALID_SUBJECT_TOKEN',
-  /** The subject token type is not supported or not recognized */
-  UNSUPPORTED_TOKEN_TYPE: 'UNSUPPORTED_TOKEN_TYPE',
-  /** Custom Token Exchange is not configured or enabled for this Auth0 tenant */
-  TOKEN_EXCHANGE_NOT_CONFIGURED: 'TOKEN_EXCHANGE_NOT_CONFIGURED',
-  /** The requested audience is invalid or not allowed */
-  INVALID_AUDIENCE: 'INVALID_AUDIENCE',
-  /** The requested scope is invalid or not allowed */
-  INVALID_SCOPE: 'INVALID_SCOPE',
-  /** Token exchange was denied by the authorization server */
-  TOKEN_EXCHANGE_DENIED: 'TOKEN_EXCHANGE_DENIED',
-  /** The token validation in Auth0 Action failed */
-  TOKEN_VALIDATION_FAILED: 'TOKEN_VALIDATION_FAILED',
-  /** Network error occurred during token exchange */
-  NETWORK_ERROR: 'NETWORK_ERROR',
-  /** The authorization server encountered an internal error */
-  SERVER_ERROR: 'SERVER_ERROR',
-  /** Unknown or uncategorized token exchange error */
-  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
-} as const;
-
-/**
- * Type for the values of CustomTokenExchangeErrorCodes.
- */
-export type CustomTokenExchangeErrorCode =
-  (typeof CustomTokenExchangeErrorCodes)[keyof typeof CustomTokenExchangeErrorCodes];
-
-const ERROR_CODE_MAP: Record<string, CustomTokenExchangeErrorCode> = {
-  // RFC 8693 OAuth 2.0 Token Exchange standard error codes
-  'invalid_request': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-  'invalid_grant': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-  'invalid_token': CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-  'unsupported_token_type':
-    CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
-  'invalid_target': CustomTokenExchangeErrorCodes.INVALID_AUDIENCE,
-  'invalid_scope': CustomTokenExchangeErrorCodes.INVALID_SCOPE,
-  'access_denied': CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
-  'unauthorized_client':
-    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-  'server_error': CustomTokenExchangeErrorCodes.SERVER_ERROR,
-
-  // Auth0-specific error codes
-  'a0.token_exchange_failed':
-    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
-  'a0.token_exchange_not_enabled':
-    CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-  'a0.invalid_subject_token':
-    CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-  'a0.subject_token_expired':
-    CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-  'a0.subject_token_validation_failed':
-    CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-  'a0.action_failed': CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-  'a0.network_error': CustomTokenExchangeErrorCodes.NETWORK_ERROR,
-};
-
-/**
- * Represents an error that occurred during Custom Token Exchange (RFC 8693).
- *
- * This error class provides structured error handling for token exchange operations,
- * with platform-agnostic error codes that normalize errors from iOS, Android, and web platforms.
- *
- * Custom Token Exchange allows exchanging external identity provider tokens for Auth0 tokens.
- * Common failure scenarios include:
- * - Invalid or expired external tokens
- * - Unsupported token types
- * - Missing or misconfigured Auth0 Actions for token validation
- * - Network connectivity issues
- *
- * @example
- * ```typescript
- * import {
- *   CustomTokenExchangeError,
- *   CustomTokenExchangeErrorCodes
- * } from 'react-native-auth0';
- *
- * try {
- *   // Exchange a standard JWT from external OIDC provider
- *   const credentials = await auth0.customTokenExchange({
- *     subjectToken: externalToken,
- *     subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
- *     audience: 'https://api.example.com',
- *   });
- * } catch (e) {
- *   if (e instanceof CustomTokenExchangeError) {
- *     console.log('Error type:', e.type);
- *     console.log('Error message:', e.message);
- *
- *     if (e.type === CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED) {
- *       // Prompt user or admin to configure Custom Token Exchange
- *     }
- *   }
- * }
- * ```
- *
- * @see {@link CustomTokenExchangeErrorCodes}
- * @see {@link https://datatracker.ietf.org/doc/html/rfc8693|RFC 8693 - OAuth 2.0 Token Exchange}
- * @see {@link https://auth0.com/docs/authenticate/custom-token-exchange|Auth0 Custom Token Exchange}
- */
-export class CustomTokenExchangeError extends Error {
-  /**
-   * The platform-agnostic error type. Use this for switch statements and error handling.
-   */
-  public readonly type: CustomTokenExchangeErrorCode;
-
-  /**
-   * The underlying raw error that caused this CustomTokenExchangeError.
-   */
-  public readonly underlyingError: AuthError;
-
-  /**
-   * Creates a new CustomTokenExchangeError.
-   *
-   * Typically you won't need to construct this directly - the SDK automatically
-   * wraps native errors in this class when they occur during token exchange operations.
-   *
-   * @param underlyingError The original AuthError from the platform.
-   */
-  constructor(underlyingError: AuthError) {
-    super(underlyingError.message);
-    this.name = 'CustomTokenExchangeError';
-    this.underlyingError = underlyingError;
-
-    // Map the raw error code to a platform-agnostic type
-    const rawCode = underlyingError.code || underlyingError.name;
-    this.type =
-      ERROR_CODE_MAP[rawCode] ?? CustomTokenExchangeErrorCodes.UNKNOWN_ERROR;
-
-    // Capture stack trace in V8 environments
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, CustomTokenExchangeError);
-    }
-  }
-
-  /**
-   * Factory method to create a CustomTokenExchangeError from a raw error.
-   *
-   * @param error The error to wrap.
-   * @returns A new CustomTokenExchangeError instance.
-   */
-  static from(error: unknown): CustomTokenExchangeError {
-    if (error instanceof CustomTokenExchangeError) {
-      return error;
-    }
-
-    if (error instanceof AuthError) {
-      return new CustomTokenExchangeError(error);
-    }
-
-    // Handle generic errors or unknown error types
-    const authError = new AuthError(
-      'custom_token_exchange_error',
-      error instanceof Error ? error.message : String(error),
-      {
-        code: 'custom_token_exchange_error',
-        json: error,
-      }
-    );
-    return new CustomTokenExchangeError(authError);
-  }
-}
diff --git a/src/core/models/__tests__/CustomTokenExchangeError.spec.ts b/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
deleted file mode 100644
index cb1506d9..00000000
--- a/src/core/models/__tests__/CustomTokenExchangeError.spec.ts
+++ /dev/null
@@ -1,193 +0,0 @@
-import {
-  CustomTokenExchangeError,
-  CustomTokenExchangeErrorCodes,
-} from '../CustomTokenExchangeError';
-import { AuthError } from '../AuthError';
-
-describe('CustomTokenExchangeError', () => {
-  describe('constructor', () => {
-    it('should create error with correct name', () => {
-      const authError = new AuthError('invalid_grant', 'Token expired', {
-        code: 'invalid_grant',
-      });
-      const error = new CustomTokenExchangeError(authError);
-
-      expect(error.name).toBe('CustomTokenExchangeError');
-    });
-
-    it('should preserve the underlying error', () => {
-      const authError = new AuthError('invalid_grant', 'Token expired', {
-        code: 'invalid_grant',
-      });
-      const error = new CustomTokenExchangeError(authError);
-
-      expect(error.underlyingError).toBe(authError);
-    });
-
-    it('should preserve the error message', () => {
-      const authError = new AuthError('invalid_grant', 'Token expired', {
-        code: 'invalid_grant',
-      });
-      const error = new CustomTokenExchangeError(authError);
-
-      expect(error.message).toBe('Token expired');
-    });
-  });
-
-  describe('error code mapping', () => {
-    it.each([
-      // RFC 8693 error codes
-      ['invalid_request', CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN],
-      ['invalid_grant', CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN],
-      ['invalid_token', CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN],
-      [
-        'unsupported_token_type',
-        CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE,
-      ],
-      ['invalid_target', CustomTokenExchangeErrorCodes.INVALID_AUDIENCE],
-      ['invalid_scope', CustomTokenExchangeErrorCodes.INVALID_SCOPE],
-      ['access_denied', CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED],
-      [
-        'unauthorized_client',
-        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-      ],
-      ['server_error', CustomTokenExchangeErrorCodes.SERVER_ERROR],
-
-      // Auth0-specific error codes
-      [
-        'a0.token_exchange_failed',
-        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED,
-      ],
-      [
-        'a0.token_exchange_not_enabled',
-        CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED,
-      ],
-      [
-        'a0.invalid_subject_token',
-        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-      ],
-      [
-        'a0.subject_token_expired',
-        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN,
-      ],
-      [
-        'a0.subject_token_validation_failed',
-        CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-      ],
-      [
-        'a0.action_failed',
-        CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED,
-      ],
-
-      // Network errors
-      ['a0.network_error', CustomTokenExchangeErrorCodes.NETWORK_ERROR],
-    ])('should map "%s" to %s', (errorCode, expectedType) => {
-      const authError = new AuthError(errorCode, 'Test error', {
-        code: errorCode,
-      });
-      const error = new CustomTokenExchangeError(authError);
-
-      expect(error.type).toBe(expectedType);
-    });
-
-    it('should map unknown error codes to UNKNOWN_ERROR', () => {
-      const authError = new AuthError('some_unknown_code', 'Unknown error', {
-        code: 'some_unknown_code',
-      });
-      const error = new CustomTokenExchangeError(authError);
-
-      expect(error.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
-    });
-
-    it('should use default code when code is not explicitly provided', () => {
-      // When code is not provided in details, AuthError defaults to 'unknown_error'
-      const authError = new AuthError('invalid_grant', 'Test error');
-      const error = new CustomTokenExchangeError(authError);
-
-      // Since code defaults to 'unknown_error', it maps to UNKNOWN_ERROR
-      expect(error.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
-    });
-
-    it('should prefer explicit code over name when mapping error type', () => {
-      const authError = new AuthError('some_name', 'Test error', {
-        code: 'invalid_grant',
-      });
-      const error = new CustomTokenExchangeError(authError);
-
-      expect(error.type).toBe(
-        CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN
-      );
-    });
-  });
-
-  describe('from factory method', () => {
-    it('should return the same error if already a CustomTokenExchangeError', () => {
-      const authError = new AuthError('invalid_grant', 'Test error');
-      const originalError = new CustomTokenExchangeError(authError);
-      const result = CustomTokenExchangeError.from(originalError);
-
-      expect(result).toBe(originalError);
-    });
-
-    it('should wrap AuthError in CustomTokenExchangeError', () => {
-      const authError = new AuthError('invalid_grant', 'Test error', {
-        code: 'invalid_grant',
-      });
-      const result = CustomTokenExchangeError.from(authError);
-
-      expect(result).toBeInstanceOf(CustomTokenExchangeError);
-      expect(result.underlyingError).toBe(authError);
-    });
-
-    it('should wrap generic Error in CustomTokenExchangeError', () => {
-      const genericError = new Error('Something went wrong');
-      const result = CustomTokenExchangeError.from(genericError);
-
-      expect(result).toBeInstanceOf(CustomTokenExchangeError);
-      expect(result.message).toBe('Something went wrong');
-      expect(result.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
-    });
-
-    it('should wrap string error in CustomTokenExchangeError', () => {
-      const result = CustomTokenExchangeError.from('String error message');
-
-      expect(result).toBeInstanceOf(CustomTokenExchangeError);
-      expect(result.message).toBe('String error message');
-      expect(result.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
-    });
-
-    it('should handle null/undefined errors', () => {
-      const result = CustomTokenExchangeError.from(null);
-
-      expect(result).toBeInstanceOf(CustomTokenExchangeError);
-      expect(result.type).toBe(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR);
-    });
-  });
-
-  describe('CustomTokenExchangeErrorCodes', () => {
-    it('should export all expected error codes', () => {
-      expect(CustomTokenExchangeErrorCodes.INVALID_SUBJECT_TOKEN).toBe(
-        'INVALID_SUBJECT_TOKEN'
-      );
-      expect(CustomTokenExchangeErrorCodes.UNSUPPORTED_TOKEN_TYPE).toBe(
-        'UNSUPPORTED_TOKEN_TYPE'
-      );
-      expect(CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_NOT_CONFIGURED).toBe(
-        'TOKEN_EXCHANGE_NOT_CONFIGURED'
-      );
-      expect(CustomTokenExchangeErrorCodes.INVALID_AUDIENCE).toBe(
-        'INVALID_AUDIENCE'
-      );
-      expect(CustomTokenExchangeErrorCodes.INVALID_SCOPE).toBe('INVALID_SCOPE');
-      expect(CustomTokenExchangeErrorCodes.TOKEN_EXCHANGE_DENIED).toBe(
-        'TOKEN_EXCHANGE_DENIED'
-      );
-      expect(CustomTokenExchangeErrorCodes.TOKEN_VALIDATION_FAILED).toBe(
-        'TOKEN_VALIDATION_FAILED'
-      );
-      expect(CustomTokenExchangeErrorCodes.NETWORK_ERROR).toBe('NETWORK_ERROR');
-      expect(CustomTokenExchangeErrorCodes.SERVER_ERROR).toBe('SERVER_ERROR');
-      expect(CustomTokenExchangeErrorCodes.UNKNOWN_ERROR).toBe('UNKNOWN_ERROR');
-    });
-  });
-});
diff --git a/src/types/parameters.ts b/src/types/parameters.ts
index 948d4e35..6e33c2ff 100644
--- a/src/types/parameters.ts
+++ b/src/types/parameters.ts
@@ -134,21 +134,19 @@ export interface CustomTokenExchangeParameters {
   /**
    * The type identifier for the subject token being exchanged.
    *
-   * For standard OAuth tokens (e.g., from OIDC providers), use RFC 8693 standard types:
-   * - `urn:ietf:params:oauth:token-type:jwt` - For JWTs (ID tokens, signed access tokens)
-   * - `urn:ietf:params:oauth:token-type:access_token` - For OAuth access tokens
-   * - `urn:ietf:params:oauth:token-type:refresh_token` - For OAuth refresh tokens
-   * - `urn:ietf:params:oauth:token-type:id_token` - For OIDC ID tokens
-   * - `urn:ietf:params:oauth:token-type:saml1` - For SAML 1.1 assertions
-   * - `urn:ietf:params:oauth:token-type:saml2` - For SAML 2.0 assertions
+   * Must be a unique profile token type URI starting with `https://` or `urn:`.
    *
-   * For custom/legacy tokens, use organization-controlled URIs. Forbidden patterns for custom types:
-   * - `urn:ietf:params:oauth:*` (IETF reserved for standard types only)
-   * - `https://auth0.com/*` (Auth0 reserved)
-   * - `urn:auth0:*` (Auth0 reserved)
+   * Valid patterns:
+   * - `urn:yourcompany:token-type` - Company-specific URN (recommended)
+   * - `https://yourcompany.com/tokens/custom` - HTTPS URL under your control
+   *
+   * Reserved namespaces (forbidden):
+   * - `http://auth0.com/*`, `https://auth0.com/*`
+   * - `http://okta.com/*`, `https://okta.com/*`
+   * - `urn:ietf:*`, `urn:auth0:*`, `urn:okta:*`
    *
    * @example "urn:acme:legacy-system-token" // Custom legacy token
-   * @example "urn:ietf:params:oauth:token-type:jwt" // Standard JWT from OIDC provider
+   * @example "https://yourcompany.com/tokens/partner-jwt" // Custom HTTPS identifier
    */
   subjectTokenType: string;