auth0-api-python 1.0.0b4__tar.gz → 1.0.0b6__tar.gz

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: auth0-api-python
-Version: 1.0.0b4
+Version: 1.0.0b6
 Summary: SDK for verifying access tokens and securing APIs with Auth0, using Authlib.
 License: MIT
+License-File: LICENSE
 Author: Auth0
 Author-email: support@auth0.com
 Requires-Python: >=3.9,<4.0
@@ -13,7 +14,8 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: ada-url (>=1.25.0,<2.0.0)
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ada-url (>=1.27.0,<2.0.0)
 Requires-Dist: authlib (>=1.0,<2.0)
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
@@ -49,6 +51,15 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 
 - [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0.
 
+## Related SDKs
+
+This library is part of Auth0's Python ecosystem for server-side authentication and API security. Related SDKs:
+
+- **[auth0-auth-js](https://github.com/auth0/auth0-auth-js)** - JavaScript/TypeScript monorepo containing:
+  - `@auth0/auth0-auth-js` - Core authentication client (low-level primitives)
+  - `@auth0/auth0-api-js` - Server-side API security (Node.js equivalent of this library)
+  - `@auth0/auth0-server-js` - Server-side web app authentication (session management)
+
 ## Getting Started
 
 ### 1. Install the SDK
@@ -106,6 +117,123 @@ asyncio.run(main())
 
 In this example, the returned dictionary contains the decoded claims (like `sub`, `scope`, etc.) from the verified token.
 
+### 4. Get an access token for a connection
+
+If you need to get an access token for an upstream idp via a connection, you can use the `get_access_token_for_connection` method:
+
+```python
+import asyncio
+
+from auth0_api_python import ApiClient, ApiClientOptions
+
+async def main():
+    api_client = ApiClient(ApiClientOptions(
+        domain="<AUTH0_DOMAIN>",
+        audience="<AUTH0_AUDIENCE>",
+        client_id="<AUTH0_CLIENT_ID>",
+        client_secret="<AUTH0_CLIENT_SECRET>",
+    ))
+    connection = "my-connection" # The Auth0 connection to the upstream idp
+    access_token = "..." # The Auth0 access token to exchange
+
+    connection_access_token = await api_client.get_access_token_for_connection({"connection": connection, "access_token": access_token})
+    # The returned token is the access token for the upstream idp
+    print(connection_access_token)
+
+asyncio.run(main())
+```
+
+More info https://auth0.com/docs/secure/tokens/token-vault
+
+### 5. Custom Token Exchange (Early Access)
+
+> [!NOTE]
+> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access) for Enterprise customers. Please reach out to Auth0 support to get it enabled for your tenant.
+
+This feature requires a [confidential client](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications) (both `client_id` and `client_secret` must be configured).
+
+Custom Token Exchange allows you to exchange a subject token for Auth0 tokens using RFC 8693. This is useful for:
+- Getting Auth0 tokens for another audience
+- Integrating external identity providers
+- Migrating to Auth0
+
+```python
+import asyncio
+
+from auth0_api_python import ApiClient, ApiClientOptions
+
+async def main():
+    api_client = ApiClient(ApiClientOptions(
+        domain="<AUTH0_DOMAIN>",
+        audience="<AUTH0_AUDIENCE>",
+        client_id="<AUTH0_CLIENT_ID>",
+        client_secret="<AUTH0_CLIENT_SECRET>",
+        timeout=10.0  # Optional: HTTP timeout in seconds (default: 10.0)
+    ))
+
+    subject_token = "..."  # Token from your legacy system or external source
+
+    result = await api_client.get_token_by_exchange_profile(
+        subject_token=subject_token,
+        subject_token_type="urn:example:subject-token",
+        audience="https://api.example.com",  # Optional - omit if your Action or tenant configuration sets the audience
+        scope="openid profile email",  # Optional
+        requested_token_type="urn:ietf:params:oauth:token-type:access_token"  # Optional
+    )
+
+    # Result contains access_token, expires_in, expires_at
+    # id_token, refresh_token, and scope are profile/Action dependent (not guaranteed; scope may be empty)
+
+asyncio.run(main())
+```
+
+**Important:**
+- Client authentication is sent via HTTP Basic (`client_id`/`client_secret`), not in the form body.
+- Do not prefix `subject_token` with "Bearer " - send the raw token value only (checked case-insensitively).
+- The `subject_token_type` must match a Token Exchange Profile configured in Auth0. This URI identifies which profile will process the exchange and **must not use reserved OAuth namespaces (IETF or vendor-controlled)**. Use your own collision-resistant namespace. See the [Custom Token Exchange documentation](https://auth0.com/docs/authenticate/custom-token-exchange) for naming guidance.
+- If neither an explicit `audience` nor tenant/Action logic sets it, you may receive a token not targeted at your API.
+
+#### Additional Parameters
+
+You can pass additional parameters for your Token Exchange Profile or Actions via the `extra` parameter. These are sent as form fields to Auth0 and may be inspected by Actions:
+
+```python
+result = await api_client.get_token_by_exchange_profile(
+    subject_token=subject_token,
+    subject_token_type="urn:example:subject-token",
+    audience="https://api.example.com",
+    extra={
+        "device_id": "device-12345",
+        "session_id": "sess-abc"
+    }
+)
+```
+
+> [!WARNING]
+> Extra parameters are sent as form fields and may appear in logs. Do not include secrets or sensitive data. Reserved OAuth parameter names (like `grant_type`, `client_id`, `scope`) cannot be used and will raise an error. Arrays are supported but limited to 20 values per key to prevent abuse.
+
+#### Error Handling
+
+```python
+from auth0_api_python import GetTokenByExchangeProfileError, ApiError
+
+try:
+    result = await api_client.get_token_by_exchange_profile(
+        subject_token=subject_token,
+        subject_token_type="urn:example:subject-token"
+    )
+except GetTokenByExchangeProfileError as e:
+    # Validation errors (invalid token format, missing credentials, reserved params, etc.)
+    print(f"Validation error: {e}")
+except ApiError as e:
+    # Token endpoint errors (invalid_grant, network issues, malformed responses, etc.)
+    print(f"API error: {e.code} - {e.message} (status: {e.status_code})")
+```
+
+**Related SDKs:** [auth0-auth-js](https://github.com/auth0/auth0-auth-js) (see `@auth0/auth0-api-js` package for Node.js equivalent)
+
+More info: https://auth0.com/docs/authenticate/custom-token-exchange
+
 #### Requiring Additional Claims
 
 If your application demands extra claims, specify them with `required_claims`:
@@ -119,7 +247,7 @@ decoded_and_verified_token = await api_client.verify_access_token(
 
 If the token lacks `my_custom_claim` or fails any standard check (issuer mismatch, expired token, invalid signature), the method raises a `VerifyAccessTokenError`.
 
-### 4. DPoP Authentication
+### 6. DPoP Authentication
 
 > [!NOTE]  
 > This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/README.md

@@ -28,6 +28,15 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 
 - [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0.
 
+## Related SDKs
+
+This library is part of Auth0's Python ecosystem for server-side authentication and API security. Related SDKs:
+
+- **[auth0-auth-js](https://github.com/auth0/auth0-auth-js)** - JavaScript/TypeScript monorepo containing:
+  - `@auth0/auth0-auth-js` - Core authentication client (low-level primitives)
+  - `@auth0/auth0-api-js` - Server-side API security (Node.js equivalent of this library)
+  - `@auth0/auth0-server-js` - Server-side web app authentication (session management)
+
 ## Getting Started
 
 ### 1. Install the SDK
@@ -85,6 +94,123 @@ asyncio.run(main())
 
 In this example, the returned dictionary contains the decoded claims (like `sub`, `scope`, etc.) from the verified token.
 
+### 4. Get an access token for a connection
+
+If you need to get an access token for an upstream idp via a connection, you can use the `get_access_token_for_connection` method:
+
+```python
+import asyncio
+
+from auth0_api_python import ApiClient, ApiClientOptions
+
+async def main():
+    api_client = ApiClient(ApiClientOptions(
+        domain="<AUTH0_DOMAIN>",
+        audience="<AUTH0_AUDIENCE>",
+        client_id="<AUTH0_CLIENT_ID>",
+        client_secret="<AUTH0_CLIENT_SECRET>",
+    ))
+    connection = "my-connection" # The Auth0 connection to the upstream idp
+    access_token = "..." # The Auth0 access token to exchange
+
+    connection_access_token = await api_client.get_access_token_for_connection({"connection": connection, "access_token": access_token})
+    # The returned token is the access token for the upstream idp
+    print(connection_access_token)
+
+asyncio.run(main())
+```
+
+More info https://auth0.com/docs/secure/tokens/token-vault
+
+### 5. Custom Token Exchange (Early Access)
+
+> [!NOTE]
+> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access) for Enterprise customers. Please reach out to Auth0 support to get it enabled for your tenant.
+
+This feature requires a [confidential client](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications) (both `client_id` and `client_secret` must be configured).
+
+Custom Token Exchange allows you to exchange a subject token for Auth0 tokens using RFC 8693. This is useful for:
+- Getting Auth0 tokens for another audience
+- Integrating external identity providers
+- Migrating to Auth0
+
+```python
+import asyncio
+
+from auth0_api_python import ApiClient, ApiClientOptions
+
+async def main():
+    api_client = ApiClient(ApiClientOptions(
+        domain="<AUTH0_DOMAIN>",
+        audience="<AUTH0_AUDIENCE>",
+        client_id="<AUTH0_CLIENT_ID>",
+        client_secret="<AUTH0_CLIENT_SECRET>",
+        timeout=10.0  # Optional: HTTP timeout in seconds (default: 10.0)
+    ))
+
+    subject_token = "..."  # Token from your legacy system or external source
+
+    result = await api_client.get_token_by_exchange_profile(
+        subject_token=subject_token,
+        subject_token_type="urn:example:subject-token",
+        audience="https://api.example.com",  # Optional - omit if your Action or tenant configuration sets the audience
+        scope="openid profile email",  # Optional
+        requested_token_type="urn:ietf:params:oauth:token-type:access_token"  # Optional
+    )
+
+    # Result contains access_token, expires_in, expires_at
+    # id_token, refresh_token, and scope are profile/Action dependent (not guaranteed; scope may be empty)
+
+asyncio.run(main())
+```
+
+**Important:**
+- Client authentication is sent via HTTP Basic (`client_id`/`client_secret`), not in the form body.
+- Do not prefix `subject_token` with "Bearer " - send the raw token value only (checked case-insensitively).
+- The `subject_token_type` must match a Token Exchange Profile configured in Auth0. This URI identifies which profile will process the exchange and **must not use reserved OAuth namespaces (IETF or vendor-controlled)**. Use your own collision-resistant namespace. See the [Custom Token Exchange documentation](https://auth0.com/docs/authenticate/custom-token-exchange) for naming guidance.
+- If neither an explicit `audience` nor tenant/Action logic sets it, you may receive a token not targeted at your API.
+
+#### Additional Parameters
+
+You can pass additional parameters for your Token Exchange Profile or Actions via the `extra` parameter. These are sent as form fields to Auth0 and may be inspected by Actions:
+
+```python
+result = await api_client.get_token_by_exchange_profile(
+    subject_token=subject_token,
+    subject_token_type="urn:example:subject-token",
+    audience="https://api.example.com",
+    extra={
+        "device_id": "device-12345",
+        "session_id": "sess-abc"
+    }
+)
+```
+
+> [!WARNING]
+> Extra parameters are sent as form fields and may appear in logs. Do not include secrets or sensitive data. Reserved OAuth parameter names (like `grant_type`, `client_id`, `scope`) cannot be used and will raise an error. Arrays are supported but limited to 20 values per key to prevent abuse.
+
+#### Error Handling
+
+```python
+from auth0_api_python import GetTokenByExchangeProfileError, ApiError
+
+try:
+    result = await api_client.get_token_by_exchange_profile(
+        subject_token=subject_token,
+        subject_token_type="urn:example:subject-token"
+    )
+except GetTokenByExchangeProfileError as e:
+    # Validation errors (invalid token format, missing credentials, reserved params, etc.)
+    print(f"Validation error: {e}")
+except ApiError as e:
+    # Token endpoint errors (invalid_grant, network issues, malformed responses, etc.)
+    print(f"API error: {e.code} - {e.message} (status: {e.status_code})")
+```
+
+**Related SDKs:** [auth0-auth-js](https://github.com/auth0/auth0-auth-js) (see `@auth0/auth0-api-js` package for Node.js equivalent)
+
+More info: https://auth0.com/docs/authenticate/custom-token-exchange
+
 #### Requiring Additional Claims
 
 If your application demands extra claims, specify them with `required_claims`:
@@ -98,7 +224,7 @@ decoded_and_verified_token = await api_client.verify_access_token(
 
 If the token lacks `my_custom_claim` or fails any standard check (issuer mismatch, expired token, invalid signature), the method raises a `VerifyAccessTokenError`.
 
-### 4. DPoP Authentication
+### 6. DPoP Authentication
 
 > [!NOTE]  
 > This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-api-python"
-version = "1.0.0.b4"
+version = "1.0.0.b6"
 description = "SDK for verifying access tokens and securing APIs with Auth0, using Authlib."
 authors = ["Auth0 <support@auth0.com>"]
 license = "MIT"
@@ -15,15 +15,16 @@ python = "^3.9"
 authlib = "^1.0"      # For JWT/OIDC features
 requests = "^2.31.0"  # If you use requests for HTTP calls (e.g., discovery)
 httpx = "^0.28.1"
-ada-url = "^1.25.0"
+ada-url = "^1.27.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0"
 pytest-cov = "^4.0"
-pytest-asyncio = "^0.20.3"
-pytest-mock = "^3.14.0"
+pytest-asyncio = "^0.25.3"
+pytest-mock = "^3.15.1"
 pytest-httpx = "^0.35.0"
-ruff = "^0.1.0"
+ruff = ">=0.1,<0.15"
+freezegun = "^1.5.5"
 
 [tool.pytest.ini_options]
 addopts = "--cov=src --cov-report=term-missing:skip-covered --cov-report=xml"

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/src/auth0_api_python/__init__.py

@@ -7,8 +7,11 @@ in server-side APIs, using Authlib for OIDC discovery and JWKS fetching.
 
 from .api_client import ApiClient
 from .config import ApiClientOptions
+from .errors import ApiError, GetTokenByExchangeProfileError
 
 __all__ = [
     "ApiClient",
-    "ApiClientOptions"
+    "ApiClientOptions",
+    "ApiError",
+    "GetTokenByExchangeProfileError"
 ]

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/src/auth0_api_python/api_client.py

@@ -1,11 +1,16 @@
 import time
-from typing import Any, Optional
+from collections.abc import Mapping, Sequence
+from typing import Any, Optional, Union
 
+import httpx
 from authlib.jose import JsonWebKey, JsonWebToken
 
 from .config import ApiClientOptions
 from .errors import (
+    ApiError,
     BaseAuthError,
+    GetAccessTokenForConnectionError,
+    GetTokenByExchangeProfileError,
     InvalidAuthSchemeError,
     InvalidDpopProofError,
     MissingAuthorizationError,
@@ -21,6 +26,20 @@ from .utils import (
     sha256_base64url,
 )
 
+# Token Exchange constants
+TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"  # noqa: S105
+MAX_ARRAY_VALUES_PER_KEY = 20  # DoS protection for extra parameter arrays
+
+# OAuth parameter denylist - parameters that cannot be overridden via extras
+RESERVED_PARAMS = frozenset([
+    "grant_type", "client_id", "client_secret", "client_assertion",
+    "client_assertion_type", "subject_token", "subject_token_type",
+    "requested_token_type", "actor_token", "actor_token_type",
+    "subject_issuer", "audience", "aud", "resource", "resources",
+    "resource_indicator", "scope", "connection", "login_hint",
+    "organization", "assertion",
+])
+
 
 class ApiClient:
     """
@@ -59,6 +78,12 @@ class ApiClient:
           • If scheme is 'DPoP', verifies both access token and DPoP proof
           • If scheme is 'Bearer', verifies only the access token
 
+        Note:
+            Authorization header parsing uses split(None, 1) to correctly handle
+            tabs and multiple spaces per HTTP specs. Malformed headers with multiple
+            spaces now raise VerifyAccessTokenError during JWT parsing (previously
+            raised InvalidAuthSchemeError).
+
         Args:
             headers: HTTP headers dict containing (header keys should be lowercase):
                 - "authorization": The Authorization header value (required)
@@ -75,6 +100,9 @@ class ApiClient:
             InvalidDpopProofError: If DPoP verification fails
             VerifyAccessTokenError: If access token verification fails
         """
+        # Normalize header keys to lowercase for robust access
+        headers = {k.lower(): v for k, v in headers.items()}
+
         authorization_header = headers.get("authorization", "")
         dpop_proof = headers.get("dpop")
 
@@ -83,22 +111,16 @@ class ApiClient:
                 raise self._prepare_error(
                         InvalidAuthSchemeError("")
                     )
-            else :
+            else:
                 raise self._prepare_error(MissingAuthorizationError())
 
-
-        parts = authorization_header.split(" ")
+        # Split authorization header on first whitespace
+        parts = authorization_header.split(None, 1)
         if len(parts) != 2:
-            if len(parts) < 2:
-                raise self._prepare_error(MissingAuthorizationError())
-            elif len(parts) > 2:
-                raise self._prepare_error(
-                    InvalidAuthSchemeError("")
-                )
+            raise self._prepare_error(MissingAuthorizationError())
 
         scheme, token = parts
-
-        scheme = scheme.strip().lower()
+        scheme = scheme.lower()
 
         if self.is_dpop_required() and scheme != "dpop":
             raise self._prepare_error(
@@ -390,8 +412,361 @@ class ApiClient:
 
         return claims
 
+    async def get_access_token_for_connection(self, options: dict[str, Any]) -> dict[str, Any]:
+        """
+        Retrieves a token for a connection.
+
+        Args:
+            options: Options for retrieving an access token for a connection.
+                Must include 'connection' and 'access_token' keys.
+                May optionally include 'login_hint'.
+
+        Raises:
+            GetAccessTokenForConnectionError: If there was an issue requesting the access token.
+            ApiError: If the token exchange endpoint returns an error.
+
+        Returns:
+            Dictionary containing the token response with access_token, expires_in, and scope.
+        """
+        # Constants
+        SUBJECT_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token"  # noqa S105
+        REQUESTED_TOKEN_TYPE_FEDERATED_CONNECTION_ACCESS_TOKEN = "http://auth0.com/oauth/token-type/federated-connection-access-token"  # noqa S105
+        GRANT_TYPE_FEDERATED_CONNECTION_ACCESS_TOKEN = "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"  # noqa S105
+        connection = options.get("connection")
+        access_token = options.get("access_token")
+
+        if not connection:
+            raise MissingRequiredArgumentError("connection")
+
+        if not access_token:
+            raise MissingRequiredArgumentError("access_token")
+
+        client_id = self.options.client_id
+        client_secret = self.options.client_secret
+        if not client_id or not client_secret:
+            raise GetAccessTokenForConnectionError("You must configure the SDK with a client_id and client_secret to use get_access_token_for_connection.")
+
+        metadata = await self._discover()
+
+        token_endpoint = metadata.get("token_endpoint")
+        if not token_endpoint:
+            raise GetAccessTokenForConnectionError(
+                "Token endpoint missing in OIDC metadata. "
+                "Verify your domain configuration and that the OIDC discovery endpoint "
+                f"(https://{self.options.domain}/.well-known/openid-configuration) is accessible"
+            )
+
+        # Prepare parameters
+        params = {
+            "connection": connection,
+            "requested_token_type": REQUESTED_TOKEN_TYPE_FEDERATED_CONNECTION_ACCESS_TOKEN,
+            "grant_type": GRANT_TYPE_FEDERATED_CONNECTION_ACCESS_TOKEN,
+            "client_id": client_id,
+            "subject_token": access_token,
+            "subject_token_type": SUBJECT_TYPE_ACCESS_TOKEN,
+        }
+
+        # Add login_hint if provided
+        if "login_hint" in options and options["login_hint"]:
+            params["login_hint"] = options["login_hint"]
+
+        try:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(self.options.timeout)) as client:
+                response = await client.post(
+                    token_endpoint,
+                    data=params,
+                    auth=(client_id, client_secret)
+                )
+
+                if response.status_code != 200:
+                    # Lenient check for JSON error responses (handles application/json, text/json, etc.)
+                    content_type = response.headers.get("content-type", "").lower()
+                    error_data = response.json() if "json" in content_type else {}
+                    raise ApiError(
+                        error_data.get("error", "connection_token_error"),
+                        error_data.get(
+                            "error_description", f"Failed to get token for connection: {response.status_code}"),
+                        response.status_code
+                    )
+
+                try:
+                    token_endpoint_response = response.json()
+                except ValueError:
+                    raise ApiError("invalid_json", "Token endpoint returned invalid JSON.")
+
+                access_token = token_endpoint_response.get("access_token")
+                if not isinstance(access_token, str) or not access_token:
+                    raise ApiError("invalid_response", "Missing or invalid access_token in response.", 502)
+
+                expires_in_raw = token_endpoint_response.get("expires_in", 3600)
+                try:
+                    expires_in = int(expires_in_raw)
+                except (TypeError, ValueError):
+                    raise ApiError("invalid_response", "expires_in is not an integer.", 502)
+
+                return {
+                    "access_token": access_token,
+                    "expires_at": int(time.time()) + expires_in,
+                    "scope": token_endpoint_response.get("scope", "")
+                }
+
+        except httpx.TimeoutException as exc:
+            raise ApiError(
+                "timeout_error",
+                f"Request to token endpoint timed out: {str(exc)}",
+                504,
+                exc
+            )
+        except httpx.HTTPError as exc:
+            raise ApiError(
+                "network_error",
+                f"Network error occurred: {str(exc)}",
+                502,
+                exc
+            )
+
+    async def get_token_by_exchange_profile(
+        self,
+        subject_token: str,
+        subject_token_type: str,
+        audience: Optional[str] = None,
+        scope: Optional[str] = None,
+        requested_token_type: Optional[str] = None,
+        extra: Optional[Mapping[str, Union[str, Sequence[str]]]] = None
+    ) -> dict[str, Any]:
+        """
+        Exchange a subject token for an Auth0 token using RFC 8693.
+
+        The matching Token Exchange Profile is selected by subject_token_type.
+        This method requires a confidential client (client_id and client_secret must be configured).
+
+        Args:
+            subject_token: The token to be exchanged
+            subject_token_type: URI identifying the token type (must match a Token Exchange Profile)
+            audience: Optional target API identifier for the exchanged tokens
+            scope: Optional space-separated OAuth 2.0 scopes to request
+            requested_token_type: Optional type of token to issue (defaults to access token)
+            extra: Optional additional parameters sent as form fields to Auth0.
+                   All values are converted to strings before sending.
+                   Arrays are limited to 20 values per key for DoS protection.
+                   Cannot override reserved OAuth parameters (case-insensitive check).
+
+        Returns:
+            Dictionary containing:
+            - access_token (str): The Auth0 access token
+            - expires_in (int): Token lifetime in seconds
+            - expires_at (int): Unix timestamp when token expires
+            - id_token (str, optional): OpenID Connect ID token
+            - refresh_token (str, optional): Refresh token
+            - scope (str, optional): Granted scopes
+            - token_type (str, optional): Token type (typically "Bearer")
+            - issued_token_type (str, optional): RFC 8693 issued token type identifier
+
+        Raises:
+            MissingRequiredArgumentError: If required parameters are missing
+            GetTokenByExchangeProfileError: If client credentials not configured, validation fails,
+                                           or reserved parameters are supplied in extra
+            ApiError: If the token endpoint returns an error
+
+        Example:
+            async def example():
+                result = await api_client.get_token_by_exchange_profile(
+                    subject_token=token,
+                    subject_token_type="urn:example:subject-token",
+                    audience="https://api.backend.com"
+                )
+
+        References:
+            - Custom Token Exchange: https://auth0.com/docs/authenticate/custom-token-exchange
+            - RFC 8693: https://datatracker.ietf.org/doc/html/rfc8693
+            - Related SDK: https://github.com/auth0/auth0-auth-js
+        """
+        # Validate required parameters
+        if not subject_token:
+            raise MissingRequiredArgumentError("subject_token")
+        if not subject_token_type:
+            raise MissingRequiredArgumentError("subject_token_type")
+
+        # Validate subject token format (fail fast to ensure token integrity)
+        tok = subject_token
+        if not isinstance(tok, str) or not tok.strip():
+            raise GetTokenByExchangeProfileError("subject_token cannot be blank or whitespace")
+        if tok != tok.strip():
+            raise GetTokenByExchangeProfileError(
+                "subject_token must not include leading or trailing whitespace"
+            )
+        if tok.lower().startswith("bearer "):
+            raise GetTokenByExchangeProfileError(
+                "subject_token must not include the 'Bearer ' prefix (case-insensitive check)"
+            )
+
+        # Require client credentials
+        client_id = self.options.client_id
+        client_secret = self.options.client_secret
+        if not client_id or not client_secret:
+            raise GetTokenByExchangeProfileError(
+                "Client credentials are required to use get_token_by_exchange_profile. "
+                "Configure client_id and client_secret in ApiClientOptions to use this feature"
+            )
+
+        # Discover token endpoint
+        metadata = await self._discover()
+        token_endpoint = metadata.get("token_endpoint")
+        if not token_endpoint:
+            raise GetTokenByExchangeProfileError(
+                "Token endpoint missing in OIDC metadata. "
+                "Verify your domain configuration and that the OIDC discovery endpoint "
+                f"(https://{self.options.domain}/.well-known/openid-configuration) is accessible"
+            )
+
+        # Build request parameters (client_id sent via HTTP Basic auth only)
+        params = {
+            "grant_type": TOKEN_EXCHANGE_GRANT_TYPE,
+            "subject_token": subject_token,
+            "subject_token_type": subject_token_type,
+        }
+
+        # Add optional parameters
+        if audience:
+            params["audience"] = audience
+        if scope:
+            params["scope"] = scope
+        if requested_token_type:
+            params["requested_token_type"] = requested_token_type
+
+        # Append extra parameters with validation
+        if extra:
+            self._apply_extra(params, extra)
+
+        # Make token exchange request
+        try:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(self.options.timeout)) as client:
+                response = await client.post(
+                    token_endpoint,
+                    data=params,
+                    auth=(client_id, client_secret)
+                )
+
+                if response.status_code != 200:
+                    error_data = {}
+                    try:
+                        # Lenient check for JSON error responses (handles application/json, text/json, etc.)
+                        content_type = response.headers.get("content-type", "").lower()
+                        if "json" in content_type:
+                            error_data = response.json()
+                    except ValueError:
+                        pass  # Ignore JSON parse errors, use generic error message below
+
+                    raise ApiError(
+                        error_data.get("error", "token_exchange_error"),
+                        error_data.get(
+                            "error_description",
+                            f"Failed to exchange token of type '{subject_token_type}'"
+                            + (f" for audience '{audience}'" if audience else "")
+                        ),
+                        response.status_code
+                    )
+
+                try:
+                    token_response = response.json()
+                except ValueError:
+                    raise ApiError("invalid_json", "Token endpoint returned invalid JSON.", 502)
+
+                # Validate required fields
+                access_token = token_response.get("access_token")
+                if not isinstance(access_token, str) or not access_token:
+                    raise ApiError(
+                        "invalid_response",
+                        "Missing or invalid access_token in response.",
+                        502
+                    )
+
+                # Lenient policy: coerce numeric strings like "3600" to int
+                # Reject non-numeric values (e.g., "not-a-number", None, objects)
+                # Reject negative values (prevent accidental "already expired" tokens)
+                expires_in_raw = token_response.get("expires_in", 3600)
+                try:
+                    expires_in = int(expires_in_raw)
+                except (TypeError, ValueError):
+                    raise ApiError("invalid_response", "expires_in is not an integer.", 502)
+
+                if expires_in < 0:
+                    raise ApiError("invalid_response", "expires_in cannot be negative.", 502)
+
+                # Build response with required fields
+                result = {
+                    "access_token": access_token,
+                    "expires_in": expires_in,
+                    "expires_at": int(time.time()) + expires_in,
+                }
+
+                # Add optional fields if present (preserves falsy values like empty scope)
+                optional_fields = ["scope", "id_token", "refresh_token", "token_type", "issued_token_type"]
+                for field in optional_fields:
+                    if field in token_response:
+                        result[field] = token_response[field]
+
+                return result
+
+        except httpx.TimeoutException as exc:
+            raise ApiError(
+                "timeout_error",
+                f"Request to token endpoint timed out: {str(exc)}",
+                504,
+                exc
+            )
+        except httpx.HTTPError as exc:
+            raise ApiError(
+                "network_error",
+                f"Network error occurred: {str(exc)}",
+                502,
+                exc
+            )
+
     # ===== Private Methods =====
 
+    def _apply_extra(
+        self,
+        params: dict[str, Any],
+        extra: Mapping[str, Union[str, Sequence[str]]]
+    ) -> None:
+        """
+        Apply extra parameters to the params dict with validation.
+
+        Args:
+            params: The parameters dict to append to
+            extra: Additional parameters to append (accepts str or sequences like list/tuple)
+
+        Raises:
+            GetTokenByExchangeProfileError: If reserved parameter, unsupported type, or array size limit exceeded
+        """
+        # Pre-compute lowercase reserved params for case-insensitive matching
+        reserved_lower = {p.lower() for p in RESERVED_PARAMS}
+
+        for k, v in extra.items():
+            key = str(k)
+            # Case-insensitive check against reserved params
+            if key.lower() in reserved_lower:
+                raise GetTokenByExchangeProfileError(
+                    f"Parameter '{k}' is reserved and cannot be overridden"
+                )
+
+            # Handle sequences (list, tuple, etc.) but reject mappings/sets/bytes
+            if isinstance(v, (dict, set, bytes)):
+                raise GetTokenByExchangeProfileError(
+                    f"Parameter '{k}' has unsupported type {type(v).__name__}. "
+                    "Only strings, numbers, booleans, and sequences (list/tuple) are allowed"
+                )
+            elif isinstance(v, (list, tuple)):
+                if len(v) > MAX_ARRAY_VALUES_PER_KEY:
+                    raise GetTokenByExchangeProfileError(
+                        f"Parameter '{k}' exceeds maximum array size of {MAX_ARRAY_VALUES_PER_KEY}"
+                    )
+                # Convert sequence items to strings
+                params[key] = [str(x) for x in v]
+            else:
+                params[key] = str(v)
+
     async def _discover(self) -> dict[str, Any]:
         """Lazy-load OIDC discovery metadata."""
         if self._metadata is None:

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/src/auth0_api_python/config.py

@@ -17,16 +17,22 @@ class ApiClientOptions:
         dpop_required: Whether DPoP is required (default: False, allows both Bearer and DPoP).
         dpop_iat_leeway: Leeway in seconds for DPoP proof iat claim (default: 30).
         dpop_iat_offset: Maximum age in seconds for DPoP proof iat claim (default: 300).
+        client_id: Required for get_access_token_for_connection and get_token_by_exchange_profile.
+        client_secret: Required for get_access_token_for_connection and get_token_by_exchange_profile.
+        timeout: HTTP timeout in seconds for token endpoint requests (default: 10.0).
     """
     def __init__(
-        self,
-        domain: str,
-        audience: str,
-        custom_fetch: Optional[Callable[..., object]] = None,
-        dpop_enabled: bool = True,
-        dpop_required: bool = False,
-        dpop_iat_leeway: int = 30,
-        dpop_iat_offset: int = 300,
+            self,
+            domain: str,
+            audience: str,
+            custom_fetch: Optional[Callable[..., object]] = None,
+            dpop_enabled: bool = True,
+            dpop_required: bool = False,
+            dpop_iat_leeway: int = 30,
+            dpop_iat_offset: int = 300,
+            client_id: Optional[str] = None,
+            client_secret: Optional[str] = None,
+            timeout: float = 10.0,
     ):
         self.domain = domain
         self.audience = audience
@@ -35,3 +41,6 @@ class ApiClientOptions:
         self.dpop_required = dpop_required
         self.dpop_iat_leeway = dpop_iat_leeway
         self.dpop_iat_offset = dpop_iat_offset
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.timeout = timeout

{auth0_api_python-1.0.0b4 → auth0_api_python-1.0.0b6}/src/auth0_api_python/errors.py

@@ -94,3 +94,49 @@ class MissingAuthorizationError(BaseAuthError):
 
     def get_error_code(self) -> str:
         return "invalid_request"
+
+
+class GetAccessTokenForConnectionError(BaseAuthError):
+    """Error raised when getting a token for a connection fails."""
+
+    def get_status_code(self) -> int:
+        return 400
+
+    def get_error_code(self) -> str:
+        return "get_access_token_for_connection_error"
+
+
+class GetTokenByExchangeProfileError(BaseAuthError):
+    """Error raised when getting a token via exchange profile fails."""
+
+    def get_status_code(self) -> int:
+        return 400
+
+    def get_error_code(self) -> str:
+        return "get_token_by_exchange_profile_error"
+
+
+class ApiError(BaseAuthError):
+    """
+    Error raised when an API request to Auth0 fails.
+    Contains details about the original error from Auth0.
+    """
+
+    def __init__(self, code: str, message: str, status_code=500, cause=None):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.cause = cause
+
+        if cause:
+            self.error = getattr(cause, "error", None)
+            self.error_description = getattr(cause, "error_description", None)
+        else:
+            self.error = None
+            self.error_description = None
+
+    def get_status_code(self) -> int:
+        return self.status_code
+
+    def get_error_code(self) -> str:
+        return self.code