Merge branch 'main' into docs/claude-md

Author: rmad17

.version

@@ -1 +1 @@
-1.0.0b13
+1.0.0b14

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## [1.0.0b14](https://github.com/auth0/auth0-server-python/tree/1.0.0b14) (2026-07-29)
+[Full Changelog](https://github.com/auth0/auth0-server-python/compare/1.0.0b13...1.0.0b14)
+
+**Added**
+- feat: add Session Transfer Token support for CTE impersonation via session transfer [\#139](https://github.com/auth0/auth0-server-python/pull/139) ([kishore7snehil](https://github.com/kishore7snehil))
+
 ## [1.0.0b13](https://github.com/auth0/auth0-server-python/tree/1.0.0b13) (2026-07-21)
 [Full Changelog](https://github.com/auth0/auth0-server-python/compare/1.0.0b12...1.0.0b13)
 

README.md

@@ -23,7 +23,7 @@ pip install auth0-server-python
 If you’re using Poetry:
 
 ```shell
-poetry install auth0-server-python
+poetry add auth0-server-python
 ```
 
 ### 2. Create the Auth0 SDK client
@@ -40,7 +40,7 @@ auth0 = ServerClient(
     client_secret='<AUTH0_CLIENT_SECRET>',
     secret='<AUTH0_SECRET>',
     authorization_params= {
-      redirect_uri: '<AUTH0_REDIRECT_URI>',
+      'redirect_uri': '<AUTH0_REDIRECT_URI>',
     }
 )
 ```
@@ -147,6 +147,11 @@ response = await auth0.custom_token_exchange(
 print(response.access_token)
 ```
 
+Building on token exchange, the SDK also supports:
+
+- **[Delegation and Impersonation](examples/CustomTokenExchange.md#3-actor-tokens-delegation)** - exchange with an `actor_token` so the issued tokens record who is acting on whose behalf (the `act` claim).
+- **[Impersonation via Session Transfer (STT)](examples/CustomTokenExchange.md#8-impersonation-via-session-transfer-stt)** - mint a Session Transfer Token to log an agent into a target app as a customer, via `request_session_transfer_token()` and `build_session_transfer_redirect()`.
+
 For more details and examples, see [examples/CustomTokenExchange.md](examples/CustomTokenExchange.md).
 
 ### 5. Multiple Custom Domains (MCD)

examples/ClientInitiatedBackChannelLogin.md

@@ -15,7 +15,7 @@ Before using backchannel authentication:
 ### Initiating Backchannel Authentication
 
 ```python
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 
 # Initialize the Auth0 client
 auth0 = ServerClient(
@@ -101,7 +101,7 @@ Read more above in [Configuring the Store](./ConfigureStore.md).
 
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 
 app = FastAPI()
 

examples/ConfigureStore.md

@@ -37,7 +37,7 @@ If you’re using `auth0-fastapi`, you already have:
 2. **CookieTransactionStore** – stores short-lived transaction data (PKCE code_verifier) in another encrypted cookie.
 
 ```python
-from store.abstract import StateStore, TransactionStore
+from auth0_server_python.store import StateStore, TransactionStore
 
 class StatelessStateStore(StateStore):
     def __init__(self, secret: str, cookie_name: str = "_a0_session"):
@@ -98,9 +98,10 @@ A **stateful** approach stores only a **session ID** in the cookie, while the ac
 ### 3.1. Redis-Based Example
 Let’s walk through a `RedisStateStore` that inherits from `StateStore`:
 ```python
+import json
 import aioredis
 from typing import Any, Dict, Optional
-from store.abstract import StateStore
+from auth0_server_python.store import StateStore
 
 class RedisStateStore(StateStore):
     """
@@ -133,7 +134,6 @@ class RedisStateStore(StateStore):
         #    encrypted_data = self.encrypt(session_id, state)
         #    await self.redis_client.set(session_id, encrypted_data)
         # For demo, let's store it as JSON without encryption:
-        import json
         await self.redis_client.set(session_id, json.dumps(state))
 
         # Now set a cookie in the response with just the session_id
@@ -166,7 +166,6 @@ class RedisStateStore(StateStore):
             return None
 
         # If you used self.encrypt(...) on set, call self.decrypt(...) here.
-        import json
         return json.loads(raw_data)
 
     async def delete(
@@ -206,7 +205,6 @@ class RedisStateStore(StateStore):
         for k in keys:
             raw_data = await self.redis_client.get(k)
             if raw_data:
-                import json
                 session_data = json.loads(raw_data)
                 # If your session_data stores an internal dict with `sid` or `sub`
                 internal = session_data.get("internal", {})
@@ -240,9 +238,10 @@ Now your user’s session data is in **Redis**, and only a minimal session ID is
 If you prefer a **SQL database** for session data, here’s a `PostgresStateStore` example using [asyncpg](https://github.com/MagicStack/asyncpg).
 
 ```python
+import json
 import asyncpg
 from typing import Any, Dict, Optional
-from store.abstract import StateStore
+from auth0_server_python.store import StateStore
 
 class PostgresStateStore(StateStore):
     """
@@ -277,7 +276,6 @@ class PostgresStateStore(StateStore):
             # Optionally encrypt `state`:
             # encrypted_data = self.encrypt(session_id, state)
             # For simplicity, store as JSON
-            import json
             data_json = json.dumps(state)
 
             # Insert or update the session
@@ -322,7 +320,6 @@ class PostgresStateStore(StateStore):
             if not row:
                 return None
             # If you used encryption, do self.decrypt(...)
-            import json
             return json.loads(row["session_data"])
 
     async def delete(

examples/CustomTokenExchange.md

@@ -179,6 +179,99 @@ Use standard URNs when possible:
 "urn:company:legacy-token"
 ```
 
+## 8. Impersonation via Session Transfer (STT)
+
+Custom Token Exchange can also mint a **Session Transfer Token (STT)** instead of an API access token. An STT lets an initiator app (for example a support console) log an agent into a target web app **as** a customer, with the agent recorded in the `act` claim - so a support engineer can reproduce a customer's exact experience without their password.
+
+This is a two-role, two-hop flow:
+
+- **Initiator** (the agent's app) mints the STT and redirects with it. This is where the new SDK methods live.
+- **Target** (the customer's app) forwards the STT to `/authorize` on a normal interactive login, which establishes the impersonated session.
+
+The STT is opaque, single-use, and short-lived (~60s). The SDK requests it and helps build the redirect - it never decodes or stores it.
+
+### Initiator: request an STT and build the redirect
+
+```python
+from auth0_server_python.auth_server.server_client import ServerClient
+from auth0_server_python.error import CustomTokenExchangeError
+
+# Mint the STT. The audience (urn:{domain}:session_transfer), grant type, and the actor are
+# set by the SDK - the actor is sourced from the logged-in agent's session.
+result = await auth0.request_session_transfer_token(
+    subject_token=subject_token,            # your proof of which customer to impersonate
+    subject_token_type="urn:acme:customer-subject",
+    organization=None,                      # optional, sent on the mint request (separate from the redirect)
+    store_options={"request": request, "response": None},
+)
+
+# result.session_transfer_token is the opaque, one-shot STT (~60s). Never store it.
+redirect_url = auth0.build_session_transfer_redirect(
+    "https://customer-app.example.com/auth/login", result, organization=None
+)
+return RedirectResponse(redirect_url)       # your framework performs the redirect
+```
+
+`SessionTransferTokenResult` carries `session_transfer_token`, `issued_token_type` (the session-transfer URN - the field to branch on), `expires_in`, and an informational `token_type` (`N_A`). There is no `act` on this result; `act` appears later, on the target session.
+
+> **NOTE**: An actor is mandatory - an STT is only issued when the Action set one. By default the SDK sources the actor from the logged-in agent's session ID token, refreshing it when expired. If the agent is not logged in (no usable session ID token and none can be refreshed), the call fails client-side with `ACTOR_UNAVAILABLE` before any network request.
+
+> **NOTE**: To use your own actor token instead of the session, pass `actor_token` (and optionally `actor_token_type`, which defaults to the ID token URN). An explicit `actor_token` takes precedence and the session is not read at all. When `actor_token_type` is the ID token URN (the default), Auth0 validates the token, so it must be:
+>
+> - Signed with RS256 or PS256 (HS256 is rejected, it uses a shared secret).
+> - Unexpired, and carrying `sub`, `iss`, `exp`, and `iat`.
+> - Issued to the same client making the exchange (its `aud` must be that client's ID).
+> - Belonging to a user who still exists and is not blocked.
+>
+> An Auth0 ID token from the agent's own session on this client satisfies all of these. A token that fails any of them is rejected by the server.
+>
+> ```python
+> result = await auth0.request_session_transfer_token(
+>     subject_token=subject_token,
+>     subject_token_type="urn:acme:customer-subject",
+>     actor_token=agent_id_token,   # explicit override - session is not used
+>     store_options={"request": request, "response": None},
+> )
+> ```
+
+### Target: forward the STT to `/authorize`
+
+On the target, the STT rides through your normal login. `start_interactive_login` forwards arbitrary authorization parameters to `/authorize`, so your login route just passes `session_transfer_token` (and `organization`, when you want the target login org-scoped) straight through:
+
+```python
+from auth0_server_python.auth_types import StartInteractiveLoginOptions
+
+url = await auth0.start_interactive_login(
+    StartInteractiveLoginOptions(authorization_params={
+        "session_transfer_token": request.query_params["session_transfer_token"],
+        # "organization": org,   # when you want the target login org-scoped
+    }),
+    store_options={"request": request, "response": None},
+)
+return RedirectResponse(url)
+```
+
+After the callback completes, read the acting party off the session user - the same way as the [Actor Tokens (Delegation)](#3-actor-tokens-delegation) section above:
+
+```python
+session = await auth0.get_session(store_options={"request": request, "response": None})
+act = (session or {}).get("user", {}).get("act")
+if act:
+    print(f"Impersonated by: {act['sub']}")   # drive an impersonation banner, etc.
+```
+
+> **NOTE**: Both clients need one-time configuration through the Auth0 Dashboard or Management API. The issuing (initiator) client must be allowed to create session transfer tokens. The redeeming (target) client must be allowed to accept delegated-access sessions and to receive the token as a query parameter. See the [Auth0 documentation](https://auth0.com/docs/authenticate/custom-token-exchange) for the exact client settings.
+
+> **NOTE**: `build_session_transfer_redirect` attaches a single-use credential to `target_login_url`, so that URL must be a trusted, app-controlled value - never one derived from untrusted input (such as a user-supplied `returnTo`), which could leak the token to an attacker host.
+
+> **NOTE**: The impersonation session is hard-capped at 2 hours and cannot mint a refresh token (`offline_access` is dropped when an actor is present). To continue past that, re-run the flow.
+
+### STT error codes
+
+- `ACTOR_UNAVAILABLE`: no usable actor token (client-side; raised before any network call)
+- `SETACTOR_REQUIRED`: an STT was requested but the Action did not call `setActor` (server 400)
+- `SESSION_TRANSFER_DISABLED`: the session-transfer feature is not enabled for the tenant/client (server 400)
+
 ## Additional Resources
 
 - [Auth0 Custom Token Exchange Documentation](https://auth0.com/docs/authenticate/custom-token-exchange)

examples/MultipleCustomDomains.md

@@ -19,7 +19,7 @@ See [Security Best Practices](#security-best-practices) for important guidance o
 For applications with a single Auth0 domain:
 
 ```python
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 
 client = ServerClient(
     domain="login.yourapp.com",  # Static string
@@ -34,7 +34,7 @@ client = ServerClient(
 For MCD support, provide a domain resolver function that receives a `DomainResolverContext`:
 
 ```python
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 from auth0_server_python.auth_types import DomainResolverContext
 
 # Map your app hostnames to Auth0 custom domains

examples/RetrievingData.md

@@ -5,12 +5,12 @@
 The SDK's `get_user()` can be used to retrieve the current logged-in user:
 
 ```python
-user = await serverClient.get_user();
+user = await server_client.get_user()
 ```
 
 ### Passing Store Options
 
-Just like most methods, `getUser` accept an argument that is used to pass to the configured Transaction and State Store:
+Just like most methods, `get_user` accept an argument that is used to pass to the configured Transaction and State Store:
 
 ```python
 store_options = {
@@ -27,7 +27,7 @@ Read more above in [Configuring the Store](./ConfigureStore.md).
 The SDK's `get_session()` can be used to retrieve the current session data:
 
 ```python
-session = await serverClient.get_session();
+session = await server_client.get_session()
 ```
 
 ### Passing Store Options
@@ -58,7 +58,7 @@ In order to do this, the SDK needs access to a Refresh Token. By default, the SD
 
 ### Passing Store Options
 
-Just like most methods, `getAccessToken` accept an argument that is used to pass to the configured Transaction and State Store:
+Just like most methods, `get_access_token` accept an argument that is used to pass to the configured Transaction and State Store:
 
 ```python
 store_options = {
@@ -225,7 +225,7 @@ token = await server_client.get_access_token(audience="https://api.example.com")
 
 # Avoid unless necessary: Dynamic scopes increase session size
 token = await server_client.get_access_token(
-    audience="https://api.example.com"
+    audience="https://api.example.com",
     scope="openid profile email read:products write:products admin:all"
 )
 ```
@@ -244,7 +244,7 @@ access_token_for_google = await server_client.get_access_token_for_connection(co
 ```
 
 - `connection`: The connection for which an access token should be retrieved, e.g. `google-oauth2` for Google.
-- `loginHint`: Optional login hint to inform which connection account to use, can be useful when multiple accounts for the connection exist for the same user. 
+- `login_hint`: Optional login hint to inform which connection account to use, can be useful when multiple accounts for the connection exist for the same user. 
 
 The SDK will cache the token internally, and return it from the cache when not expired. When no token is found in the cache, or the token is expired, calling `get_access_token_for_connection()` will call Auth0 to retrieve a new token and update the cache.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-server-python"
-version = "1.0.0b13"
+version = "1.0.0b14"
 description = "Auth0 server-side Python SDK"
 readme = "README.md"
 authors = ["Auth0 <support@okta.com>"]