feat: add custom token exchange support across all platforms

[sanchitmehta94]

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

📋 Changes

Description

Implements Custom Token Exchange (RFC 8693) feature for Auth0 Flutter SDK, enabling users to exchange external identity provider tokens for Auth0 credentials.

Dependencies Updated

Auth0 Android: 3.11.0 → 3.12.0 (adds organization parameter to customTokenExchange - Dec 2025)
Auth0.swift: 2.14.0 → 2.16.2 (adds organization parameter to customTokenExchange - Dec 2025)

Core Implementation

• Android: Added CustomTokenExchangeApiRequestHandler with organization support (requires Auth0 Android SDK 3.12.0+)
• iOS/macOS: Added AuthAPICustomTokenExchangeMethodHandler with organization support (requires Auth0.swift 2.16.0+)
• Web: Added JS interop for auth0-spa-js exchangeToken() method with organizationId support
• Platform Interface: Added AuthCustomTokenExchangeOptions and ExchangeTokenOptions classes with organization parameter

API Methods

// Mobile (Android/iOS)

  auth0.api.customTokenExchange(
    subjectToken: 'external-token',
    subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
    audience: 'https://api.example.com',
    scopes: {'openid', 'profile', 'email'},
    organization: 'org_id', // Optional - requires updated native SDKs
    parameters: {'key': 'value'} // Optional
  )

// Web

  auth0Web.customTokenExchange(
    subjectToken: 'external-token',
    subjectTokenType: 'urn:ietf:params:oauth:token-type:jwt',
    organizationId: 'org_id', // Optional
    scopes: {'openid', 'profile', 'email'}
  )

📎 References

🎯 Testing

[sanchitmehta94]

review examples.md file again

[Copilot]

Pull request overview

This PR implements Custom Token Exchange (RFC 8693) support across all platforms (Android, iOS, macOS, and Web) for the Auth0 Flutter SDK, enabling users to exchange external identity provider tokens for Auth0 credentials.

Changes:

• Added native SDK support by upgrading Auth0 Android from 3.11.0 to 3.12.0 and Auth0.swift from 2.14.0 to 2.16.2 to support organization parameters
• Implemented platform-specific handlers for custom token exchange on mobile (Android/iOS/macOS) and web platforms
• Added comprehensive test coverage for the new functionality across all platforms

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
auth0_flutter_platform_interface/lib/src/auth/auth_custom_token_exchange_options.dart	Defines options class for mobile token exchange with organization support
auth0_flutter_platform_interface/lib/src/web/exchange_token_options.dart	Defines options class for web token exchange with organizationId support
auth0_flutter_platform_interface/lib/src/auth0_flutter_auth_platform.dart	Adds platform interface method for custom token exchange
auth0_flutter_platform_interface/lib/src/method_channel_auth0_flutter_auth.dart	Implements method channel handler for custom token exchange
auth0_flutter/lib/src/mobile/authentication_api.dart	Adds public API method for mobile custom token exchange
auth0_flutter/lib/auth0_flutter_web.dart	Adds public API method for web custom token exchange
auth0_flutter/darwin/Classes/AuthAPI/AuthAPICustomTokenExchangeMethodHandler.swift	Implements Swift handler for iOS/macOS token exchange
auth0_flutter/android/src/main/kotlin/com/auth0/auth0_flutter/request_handlers/api/CustomTokenExchangeApiRequestHandler.kt	Implements Kotlin handler for Android token exchange
auth0_flutter/lib/src/web/auth0_flutter_plugin_real.dart	Implements web platform token exchange using auth0-spa-js
auth0_flutter/EXAMPLES.md	Adds documentation and usage examples for custom token exchange

Comments suppressed due to low confidence (1)

auth0_flutter/darwin/Classes/AuthAPI/AuthAPICustomTokenExchangeMethodHandler.swift:1

• The closure signature has 4 parameters but the spy method expects 5 parameters (subjectToken, subjectTokenType, audience, scope, organization). This mismatch will cause a runtime error.

import Auth0

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The web example shows a 'parameters' option that is not present in the API signature defined in auth0_flutter_web.dart. This will mislead users as the parameters option is not supported.

Suggested change

parameters: {'custom_param': 'value'} // Optional

[pmathew92]

Yes, this is not defined in the API contract