auth0-api-python 1.0.0b9__tar.gz → 1.0.0b11__tar.gz

auth0_api_python-1.0.0b9/README.md → auth0_api_python-1.0.0b11/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.4
+Name: auth0-api-python
+Version: 1.0.0b11
+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.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: ada-url (>=1.30.0,<2.0.0)
+Requires-Dist: authlib (>=1.0,<2.0)
+Requires-Dist: cryptography (>=43.0.1)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: jwcrypto (>=1.5.7,<2.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
 The `auth0-api-python` library allows you to secure APIs running on Python, particularly for verifying Auth0-issued access tokens.
 
 It’s intended as a foundation for building more framework-specific integrations (e.g., with FastAPI, Django, etc.), but you can also use it directly in any Python server-side environment.
@@ -18,6 +43,7 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 ### **Core Features**
 - **Unified Entry Point**: `verify_request()` - automatically detects and validates Bearer or DPoP schemes
 - **Multi-Custom Domain (MCD)** - Accept tokens from multiple Auth0 domains with static lists or dynamic resolvers
+- **Organization Policy** - Enforce and optionally allowlist the `org_id` claim on incoming tokens
 - **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS with per-issuer caching
 - **JWT Validation** - Complete RS256 signature verification with claim validation
 - **DPoP Proof Verification** - Full RFC 9449 compliance with ES256 signature validation
@@ -42,7 +68,7 @@ This library is part of Auth0's Python ecosystem for server-side authentication
 
 ### 1. Install the SDK
 
-_This library requires Python 3.9+._
+_This library requires Python 3.10+._
 
 ```shell
 pip install auth0-api-python
@@ -95,6 +121,12 @@ asyncio.run(main())
 
 In this example, the returned dictionary contains the decoded claims (like `sub`, `scope`, etc.) from the verified token.
 
+If the OIDC discovery document or the JWKS request cannot be reached (connection error, timeout, or an HTTP `5xx` or `429` response), the method raises `AuthServerUnavailableError`, a subclass of `VerifyAccessTokenError` with status `503` and error code `auth_server_unavailable`. Other fetch failures, such as a `404` or a malformed response, still raise `VerifyAccessTokenError`. `verify_request()` raises the same error and sets no `WWW-Authenticate` header, so clients retry later instead of requesting a new token.
+
+HTTP status codes are checked only for the default HTTP client. With `custom_fetch`, only a connection error or timeout raised by your function is reported as `AuthServerUnavailableError`.
+
+This error comes from token verification only. Where verification is skipped, such as `get_client_credentials_token()` or an exchange with `verified=`, a failed discovery request raises the underlying `httpx` error.
+
 ### 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:
@@ -114,6 +146,7 @@ async def main():
     connection = "my-connection" # The Auth0 connection to the upstream idp
     access_token = "..." # The Auth0 access token to exchange
 
+    await api_client.verify_access_token(access_token) # Verify first so the organization policy applies
     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)
@@ -121,6 +154,8 @@ async def main():
 asyncio.run(main())
 ```
 
+When a `token_store` is configured on `ApiClientOptions`, the connection token is cached by caller, connection and `login_hint`, skipping the exchange on repeat calls. Pass `verified=` with a `VerifiedToken` built from the `verify_access_token()` claims to reuse that verification rather than verifying a second time. See [Access Token for a Connection](EXAMPLES.md#access-token-for-a-connection-token-vault) for a full example and setup requirements.
+
 More info https://auth0.com/docs/secure/tokens/token-vault
 
 ### 5. Custom Token Exchange (Early Access)
@@ -250,6 +285,25 @@ token as the `subject_token` and relies on Auth0 to handle any DPoP-specific beh
 The OBO result only includes access-token-oriented fields. It does not expose `id_token` or
 `refresh_token`.
 
+Configuring a `token_store` on `ApiClientOptions` caches the exchanged token, so a repeat call for
+the same caller, audience, organization, scopes, and session reuses it instead of exchanging again.
+With no `token_store`, every call performs a fresh exchange, matching the existing behavior above.
+
+#### Client Credentials for Server-to-Server Calls
+
+Use `get_client_credentials_token()` to obtain an M2M access token for server-to-server calls
+using the OAuth 2.0 client credentials grant.
+
+```python
+result = await api_client.get_client_credentials_token(
+    audience="https://downstream-api.example.com",
+    scope="read:data",
+)
+# call downstream API with result["access_token"]
+```
+
+See the **[Client Credentials example](EXAMPLES.md#client-credentials-for-server-to-server-calls)** for a full example that calls a downstream API, plus the caching behavior.
+
 #### Inspecting Delegation After Token Verification
 
 When a downstream API or `MCP` server receives an access token that may have been issued through
@@ -406,6 +460,44 @@ For hybrid mode (migration scenarios), resolver patterns, error handling, and ca
 
 - **[Multi-Custom Domain Guide](docs/MultipleCustomDomain.md)** - Configuration modes, resolver patterns, migration, error handling
 - **[Caching Guide](docs/Caching.md)** - Cache tuning, custom adapters (Redis, Memcached)
+- **[Token Storage Guide](docs/TokenStorage.md)** - Caching OBO exchanges, custom TokenStore backends, at-rest encryption
+
+### 8. Anonymous Callers
+
+[Anonymous Sessions](https://auth0.com/docs/manage-users/sessions/anonymous-sessions) give a visitor an Auth0 identity before they log in. Session creation happens in your web application. This SDK only validates the tokens they produce. The access token is a standard Auth0 Bearer JWT, so `verify_access_token()` and `verify_request()` validate it exactly like any other token. The only difference is the `sub` claim, which starts with `anon@`.
+
+An anonymous token passes verification by default. Deciding whether an anonymous caller is authorized is your application's responsibility. See [Anonymous Callers](EXAMPLES.md#anonymous-callers) for allow, block-per-route, and block-globally patterns.
+
+### 9. Organization Policy
+
+For APIs that need to enforce an Auth0 Organization context on every request, optionally restricted to a specific set of Organizations:
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions
+
+api_client = ApiClient(ApiClientOptions(
+    domain="tenant.auth0.com",
+    audience="https://api.example.com",
+    organization_policy="required",
+    organization_id=["org_abc123", "org_def456"]
+))
+
+claims = await api_client.verify_access_token(access_token)
+```
+
+See the **[Organization Policy Guide](docs/OrganizationPolicy.md)** for policy modes, the allowlist, and error handling.
+
+### 10. Client Telemetry
+
+The SDK sends an `Auth0-Client` header and a `User-Agent` header (`Python/<version>`) on the requests it makes to Auth0 with its default HTTP client. Requests served by `custom_fetch` do not carry them. If you build a wrapper SDK on top of this one, pass `client_info` so the header names your SDK. An invalid `client_info` raises `ConfigurationError` when the client is created.
+
+```python
+api_client = ApiClient(ApiClientOptions(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>",
+    client_info={"name": "my-wrapper-sdk", "version": "1.2.3", "env": {"my-framework": "4.5.6"}},
+))
+```
 
 ## Feedback
 
@@ -440,3 +532,4 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
 <p align="center">
   This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-api-python/LICENSE"> LICENSE</a> file for more info.
 </p>
+

auth0_api_python-1.0.0b9/PKG-INFO → auth0_api_python-1.0.0b11/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.4
-Name: auth0-api-python
-Version: 1.0.0b9
-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
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: ada-url (>=1.27.0,<2.0.0) ; python_version == "3.9"
-Requires-Dist: ada-url (>=1.30.0,<2.0.0) ; python_version >= "3.10"
-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)
-Description-Content-Type: text/markdown
-
 The `auth0-api-python` library allows you to secure APIs running on Python, particularly for verifying Auth0-issued access tokens.
 
 It’s intended as a foundation for building more framework-specific integrations (e.g., with FastAPI, Django, etc.), but you can also use it directly in any Python server-side environment.
@@ -42,6 +18,7 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 ### **Core Features**
 - **Unified Entry Point**: `verify_request()` - automatically detects and validates Bearer or DPoP schemes
 - **Multi-Custom Domain (MCD)** - Accept tokens from multiple Auth0 domains with static lists or dynamic resolvers
+- **Organization Policy** - Enforce and optionally allowlist the `org_id` claim on incoming tokens
 - **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS with per-issuer caching
 - **JWT Validation** - Complete RS256 signature verification with claim validation
 - **DPoP Proof Verification** - Full RFC 9449 compliance with ES256 signature validation
@@ -66,7 +43,7 @@ This library is part of Auth0's Python ecosystem for server-side authentication
 
 ### 1. Install the SDK
 
-_This library requires Python 3.9+._
+_This library requires Python 3.10+._
 
 ```shell
 pip install auth0-api-python
@@ -119,6 +96,12 @@ asyncio.run(main())
 
 In this example, the returned dictionary contains the decoded claims (like `sub`, `scope`, etc.) from the verified token.
 
+If the OIDC discovery document or the JWKS request cannot be reached (connection error, timeout, or an HTTP `5xx` or `429` response), the method raises `AuthServerUnavailableError`, a subclass of `VerifyAccessTokenError` with status `503` and error code `auth_server_unavailable`. Other fetch failures, such as a `404` or a malformed response, still raise `VerifyAccessTokenError`. `verify_request()` raises the same error and sets no `WWW-Authenticate` header, so clients retry later instead of requesting a new token.
+
+HTTP status codes are checked only for the default HTTP client. With `custom_fetch`, only a connection error or timeout raised by your function is reported as `AuthServerUnavailableError`.
+
+This error comes from token verification only. Where verification is skipped, such as `get_client_credentials_token()` or an exchange with `verified=`, a failed discovery request raises the underlying `httpx` error.
+
 ### 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:
@@ -138,6 +121,7 @@ async def main():
     connection = "my-connection" # The Auth0 connection to the upstream idp
     access_token = "..." # The Auth0 access token to exchange
 
+    await api_client.verify_access_token(access_token) # Verify first so the organization policy applies
     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)
@@ -145,6 +129,8 @@ async def main():
 asyncio.run(main())
 ```
 
+When a `token_store` is configured on `ApiClientOptions`, the connection token is cached by caller, connection and `login_hint`, skipping the exchange on repeat calls. Pass `verified=` with a `VerifiedToken` built from the `verify_access_token()` claims to reuse that verification rather than verifying a second time. See [Access Token for a Connection](EXAMPLES.md#access-token-for-a-connection-token-vault) for a full example and setup requirements.
+
 More info https://auth0.com/docs/secure/tokens/token-vault
 
 ### 5. Custom Token Exchange (Early Access)
@@ -274,6 +260,25 @@ token as the `subject_token` and relies on Auth0 to handle any DPoP-specific beh
 The OBO result only includes access-token-oriented fields. It does not expose `id_token` or
 `refresh_token`.
 
+Configuring a `token_store` on `ApiClientOptions` caches the exchanged token, so a repeat call for
+the same caller, audience, organization, scopes, and session reuses it instead of exchanging again.
+With no `token_store`, every call performs a fresh exchange, matching the existing behavior above.
+
+#### Client Credentials for Server-to-Server Calls
+
+Use `get_client_credentials_token()` to obtain an M2M access token for server-to-server calls
+using the OAuth 2.0 client credentials grant.
+
+```python
+result = await api_client.get_client_credentials_token(
+    audience="https://downstream-api.example.com",
+    scope="read:data",
+)
+# call downstream API with result["access_token"]
+```
+
+See the **[Client Credentials example](EXAMPLES.md#client-credentials-for-server-to-server-calls)** for a full example that calls a downstream API, plus the caching behavior.
+
 #### Inspecting Delegation After Token Verification
 
 When a downstream API or `MCP` server receives an access token that may have been issued through
@@ -430,6 +435,44 @@ For hybrid mode (migration scenarios), resolver patterns, error handling, and ca
 
 - **[Multi-Custom Domain Guide](docs/MultipleCustomDomain.md)** - Configuration modes, resolver patterns, migration, error handling
 - **[Caching Guide](docs/Caching.md)** - Cache tuning, custom adapters (Redis, Memcached)
+- **[Token Storage Guide](docs/TokenStorage.md)** - Caching OBO exchanges, custom TokenStore backends, at-rest encryption
+
+### 8. Anonymous Callers
+
+[Anonymous Sessions](https://auth0.com/docs/manage-users/sessions/anonymous-sessions) give a visitor an Auth0 identity before they log in. Session creation happens in your web application. This SDK only validates the tokens they produce. The access token is a standard Auth0 Bearer JWT, so `verify_access_token()` and `verify_request()` validate it exactly like any other token. The only difference is the `sub` claim, which starts with `anon@`.
+
+An anonymous token passes verification by default. Deciding whether an anonymous caller is authorized is your application's responsibility. See [Anonymous Callers](EXAMPLES.md#anonymous-callers) for allow, block-per-route, and block-globally patterns.
+
+### 9. Organization Policy
+
+For APIs that need to enforce an Auth0 Organization context on every request, optionally restricted to a specific set of Organizations:
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions
+
+api_client = ApiClient(ApiClientOptions(
+    domain="tenant.auth0.com",
+    audience="https://api.example.com",
+    organization_policy="required",
+    organization_id=["org_abc123", "org_def456"]
+))
+
+claims = await api_client.verify_access_token(access_token)
+```
+
+See the **[Organization Policy Guide](docs/OrganizationPolicy.md)** for policy modes, the allowlist, and error handling.
+
+### 10. Client Telemetry
+
+The SDK sends an `Auth0-Client` header and a `User-Agent` header (`Python/<version>`) on the requests it makes to Auth0 with its default HTTP client. Requests served by `custom_fetch` do not carry them. If you build a wrapper SDK on top of this one, pass `client_info` so the header names your SDK. An invalid `client_info` raises `ConfigurationError` when the client is created.
+
+```python
+api_client = ApiClient(ApiClientOptions(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>",
+    client_info={"name": "my-wrapper-sdk", "version": "1.2.3", "env": {"my-framework": "4.5.6"}},
+))
+```
 
 ## Feedback
 
@@ -464,4 +507,3 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
 <p align="center">
   This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-api-python/LICENSE"> LICENSE</a> file for more info.
 </p>
-

{auth0_api_python-1.0.0b9 → auth0_api_python-1.0.0b11}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-api-python"
-version = "1.0.0b9"
+version = "1.0.0b11"
 description = "SDK for verifying access tokens and securing APIs with Auth0, using Authlib."
 authors = ["Auth0 <support@auth0.com>"]
 license = "MIT"
@@ -11,14 +11,13 @@ packages = [
 ]
 
 [tool.poetry.dependencies]
-python = "^3.9"
+python = ">=3.10"
 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 = [
-    {version = "^1.30.0", python = ">=3.10"},
-    {version = "^1.27.0", python = ">=3.9,<3.10"}
-]
+cryptography = ">=43.0.1"
+jwcrypto = "^1.5.7"
+ada-url = "^1.30.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0"

{auth0_api_python-1.0.0b9 → auth0_api_python-1.0.0b11}/src/auth0_api_python/__init__.py

@@ -11,11 +11,25 @@ from .cache import CacheAdapter, InMemoryCache
 from .config import ApiClientOptions
 from .errors import (
     ApiError,
+    AuthServerUnavailableError,
     ConfigurationError,
     DomainsResolverError,
+    GetAccessTokenForConnectionError,
+    GetClientCredentialsTokenError,
     GetTokenByExchangeProfileError,
+    MissingOrganizationError,
+    OrganizationNotAllowedError,
+    VerifyAccessTokenError,
+)
+from .token_store import (
+    AbstractTokenStore,
+    IndexedTokenStore,
+    TokenIndexMember,
+    TokenSet,
+    VerifiedToken,
 )
 from .types import (
+    ClientCredentialsTokenResult,
     DomainsResolver,
     DomainsResolverContext,
     OnBehalfOfTokenResult,
@@ -25,14 +39,26 @@ __all__ = [
     "ApiClient",
     "ApiClientOptions",
     "ApiError",
+    "AuthServerUnavailableError",
     "CacheAdapter",
+    "ClientCredentialsTokenResult",
     "ConfigurationError",
     "DomainsResolver",
     "DomainsResolverContext",
     "DomainsResolverError",
+    "GetAccessTokenForConnectionError",
+    "GetClientCredentialsTokenError",
     "GetTokenByExchangeProfileError",
+    "VerifyAccessTokenError",
     "get_current_actor",
     "get_delegation_chain",
     "InMemoryCache",
+    "MissingOrganizationError",
+    "AbstractTokenStore",
+    "IndexedTokenStore",
+    "TokenIndexMember",
+    "VerifiedToken",
     "OnBehalfOfTokenResult",
+    "OrganizationNotAllowedError",
+    "TokenSet",
 ]

auth0_api_python-1.0.0b11/src/auth0_api_python/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal machinery for auth0-api-python. Not part of the public API."""

auth0_api_python-1.0.0b11/src/auth0_api_python/_internal/cache_expiry.py

@@ -0,0 +1,9 @@
+"""Freshness rule shared by every cache of a token the SDK minted."""
+
+# A token this close to expiry is treated as expired, so it is unlikely to lapse before the caller uses it.
+EXPIRY_BUFFER_SECONDS = 30
+
+
+def is_fresh(expires_at: int, now: int) -> bool:
+    """True when a cached token still has more than the expiry buffer left."""
+    return expires_at - EXPIRY_BUFFER_SECONDS > now

auth0_api_python-1.0.0b11/src/auth0_api_python/_internal/cache_keys.py

@@ -0,0 +1,147 @@
+"""Cache-key builders and scope helpers for the tokens the SDK mints."""
+
+import hashlib
+
+from ..utils import get_unverified_payload
+
+_FIELD_SEPARATOR = "\x1f"
+
+
+def _normalized_scopes(scope: str | None) -> str:
+    """Sort and dedupe scopes so equivalent scope strings produce the same cache key."""
+    if not scope:
+        return ""
+    return " ".join(sorted(set(scope.split())))
+
+
+def is_covered_by(requested: str | None, granted: str | None) -> bool:
+    """True when the requested scopes are all covered by the granted scopes."""
+    granted_set = set(_normalized_scopes(granted).split())
+    requested_set = set(_normalized_scopes(requested).split())
+    return requested_set.issubset(granted_set)
+
+
+def session_fingerprint(access_token: str) -> str:
+    """
+    Derive a session-scoped fingerprint for an access token, to keep concurrent
+    sessions' cached tokens from colliding. Not a trust or authorization signal:
+    the token is decoded without signature verification.
+    """
+    try:
+        payload = get_unverified_payload(access_token)
+    except ValueError:
+        return hashlib.sha256(access_token.encode()).hexdigest()
+
+    sid = payload.get("sid")
+    if isinstance(sid, str) and sid:
+        return sid
+
+    jti = payload.get("jti")
+    if isinstance(jti, str) and jti:
+        return jti
+
+    return hashlib.sha256(access_token.encode()).hexdigest()
+
+
+def _obo_identity_fields(
+    namespace: str,
+    *,
+    issuer: str,
+    incoming_client_id: str,
+    exchange_tenant: str,
+    exchange_client_id: str,
+    audience: str,
+    org_id: str | None,
+    session_key: str,
+) -> list[str]:
+    """The fields every OBO cache key shares, namespaced by key kind.
+
+    Folds in the verified issuer, the incoming token's client, the exchange tenant, and the
+    exchange client so a token minted under one of them is never read back under another.
+    """
+    return [
+        namespace,
+        issuer,
+        incoming_client_id,
+        exchange_tenant,
+        exchange_client_id,
+        audience,
+        org_id or "",
+        session_key,
+    ]
+
+
+def obo_cache_key(
+    *,
+    layout: str,
+    sub: str,
+    issuer: str,
+    incoming_client_id: str,
+    exchange_tenant: str,
+    exchange_client_id: str,
+    audience: str,
+    org_id: str | None,
+    scopes: str | None,
+    session_key: str,
+) -> str:
+    """Token cache key for an On Behalf Of exchange.
+
+    layout is "strict" or "index" so the two scope-matching modes never read each other's tokens.
+    The normalized scopes are folded in.
+    """
+    fields = _obo_identity_fields(
+        "obo_token_" + layout,
+        issuer=issuer,
+        incoming_client_id=incoming_client_id,
+        exchange_tenant=exchange_tenant,
+        exchange_client_id=exchange_client_id,
+        audience=audience,
+        org_id=org_id,
+        session_key=session_key,
+    )
+    fields.append(_normalized_scopes(scopes))
+    return sub + ":" + hashlib.sha256(_FIELD_SEPARATOR.join(fields).encode()).hexdigest()
+
+
+def index_cache_key(
+    *,
+    sub: str,
+    issuer: str,
+    incoming_client_id: str,
+    exchange_tenant: str,
+    exchange_client_id: str,
+    audience: str,
+    org_id: str | None,
+    session_key: str,
+) -> str:
+    """Cache key for the OBO token index, scoped to caller, issuer, exchange, audience, org, and session.
+
+    The "obo_index" namespace keeps it from colliding with either layout's token cache key.
+    """
+    fields = _obo_identity_fields(
+        "obo_index",
+        issuer=issuer,
+        incoming_client_id=incoming_client_id,
+        exchange_tenant=exchange_tenant,
+        exchange_client_id=exchange_client_id,
+        audience=audience,
+        org_id=org_id,
+        session_key=session_key,
+    )
+    return sub + ":" + hashlib.sha256(_FIELD_SEPARATOR.join(fields).encode()).hexdigest()
+
+
+def m2m_cache_key(*, tenant: str, client_id: str, audience: str, scopes: str | None) -> str:
+    """Cache key for a client-credentials (M2M) exchange, scoped to tenant, client, audience, and scopes."""
+    fields = _FIELD_SEPARATOR.join(
+        ["m2m", tenant, client_id, audience, _normalized_scopes(scopes)]
+    )
+    return hashlib.sha256(fields.encode()).hexdigest()
+
+
+def token_vault_cache_key(
+    *, sub: str, connection: str, tenant: str, client_id: str, login_hint: str | None = None
+) -> str:
+    """Cache key for a Token Vault exchange, scoped to tenant, client, caller, connection, and login hint."""
+    fields = _FIELD_SEPARATOR.join(["token_vault", tenant, client_id, sub, connection, login_hint or ""])
+    return hashlib.sha256(fields.encode()).hexdigest()