Docs update

Author: rmad17

README.md

@@ -202,7 +202,7 @@ Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rf
 
 ### 10. Passwordless Authentication
 
-Sign users in with a one-time code sent by email or SMS, or with a magic link sent by email, via [Auth0 embedded passwordless login](https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints). OTP verification and the magic-link callback each establish a server-side session like every other login path. For prerequisites, both flows, custom scopes/audiences, organizations, step-up MFA, and error handling, see [examples/Passwordless.md](examples/Passwordless.md).
+Sign users in with a one-time code sent by email or SMS, or with a magic link sent by email, via [Auth0 embedded passwordless login](https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints). OTP verification and the magic-link callback each establish a server-side session like every other login path. For prerequisites, both flows, custom scopes/audiences, step-up MFA, and error handling, see [examples/Passwordless.md](examples/Passwordless.md).
 
 ## Feedback
 

examples/Passwordless.md

@@ -17,7 +17,6 @@ Passwordless lets users sign in with a one-time code sent by email or SMS, or wi
 - [3. Email magic link](#3-email-magic-link)
 - [4. Custom scopes and audiences](#4-custom-scopes-and-audiences)
 - [5. Forwarding the end-user IP](#5-forwarding-the-end-user-ip)
-- [6. Organizations (magic link only)](#6-organizations-magic-link-only)
 - [Completing MFA during passwordless login](#completing-mfa-during-passwordless-login)
 - [Error Handling](#error-handling)
 
@@ -254,32 +253,6 @@ result = await server_client.passwordless.verify(
 > [!WARNING]
 > Only forward a trusted, normalized end-user IP from your edge/proxy layer. Do not blindly copy arbitrary client-supplied headers into `client_ip`.
 
-## 6. Organizations (magic link only)
-
-Magic links can carry an organization through `authParams`; the SDK stores the expected organization in the transaction and validates the claims returned by the callback.
-
-```python
-await server_client.passwordless.start(
-    StartPasswordlessEmailOptions(
-        email="user@example.com",
-        send="link",
-        organization="org_abc123",
-    ),
-    store_options={"request": request, "response": response},
-)
-```
-
-If the callback's ID token does not include a matching organization claim, verification fails before a session is persisted, raising `OrganizationTokenValidationError`.
-
-> [!NOTE]
-> `VerifyPasswordlessOtpOptions` (the OTP `verify()` path) has no `organization`
-> field. Auth0 does not attach an organization claim to tokens issued by the
-> passwordless-OTP grant, so there is nothing for the SDK to validate against
-> — an OTP flow that needs organization-scoped login should use magic link
-> instead. The model rejects unknown fields, so passing `organization` to
-> `verify()` raises a pydantic `ValidationError` rather than being silently
-> dropped.
-
 ## Completing MFA during passwordless login
 
 Auth0 can require MFA during passwordless OTP verification. In that case, the SDK raises `MfaRequiredError` before it creates a session. Complete the MFA challenge with `server_client.mfa`, then persist the returned tokens according to your framework's session integration.
@@ -328,7 +301,6 @@ Passwordless methods raise typed SDK errors:
 - `MfaRequiredError` - Auth0 requires MFA before completing login
 - `MissingRequiredArgumentError` - required SDK input is missing, such as magic-link `store_options`
 - `InvalidArgumentError` - caller input is rejected before a network call
-- `OrganizationTokenValidationError` - magic-link callback only: requested organization does not match the returned token claims
 
 ### Basic handling
 

src/auth0_server_python/auth_server/passwordless_client.py

@@ -87,10 +87,11 @@ async def start(
 
         Raises:
             PasswordlessStartError: When ``POST /passwordless/start`` fails.
-            InvalidArgumentError: When caller ``auth_params`` attempts to
-                override an SDK-owned parameter.
+            InvalidArgumentError: When ``options`` is not a recognized type, or
+                caller ``auth_params`` contains an SDK-owned or unrecognized key.
             MissingRequiredArgumentError: When a magic link is requested but no
-                ``redirect_uri`` is configured on the client.
+                ``redirect_uri`` is configured on the client, or ``store_options``
+                is not provided.
         """
         client = self._client
         origin_domain = await client._resolve_current_domain(store_options)
@@ -119,10 +120,12 @@ async def start(
             isinstance(options, StartPasswordlessEmailOptions) and options.send == "link"
         )
 
+        magic_link_transaction = None
         if is_magic_link:
-            body["authParams"] = await self._build_magic_link_auth_params(
+            auth_params, magic_link_transaction = self._prepare_magic_link_start(
                 options, origin_domain, store_options
             )
+            body["authParams"] = auth_params
         elif options.auth_params:
             # OTP flows: forward safe passthrough params only.
             body["authParams"] = self._sanitize_caller_auth_params(options.auth_params)
@@ -160,6 +163,15 @@ async def start(
                 self._retry_after(response),
             )
 
+        if magic_link_transaction is not None:
+            tx_key, transaction_data = magic_link_transaction
+            await client._transaction_store.set(
+                tx_key,
+                transaction_data,
+                remove_if_expires=True,
+                options=store_options,
+            )
+
         return PasswordlessStartResult(**self._safe_json(response))
 
     # ----------------------------------------------------------------- verify
@@ -187,6 +199,9 @@ async def verify(
             PasswordlessVerifyError: When token exchange or ID-token
                 verification fails.
             MfaRequiredError: When Auth0 requires MFA before completing login.
+            ApiError: When fetching the JWKS used to verify the ID token fails.
+            SessionExpiredError: When the token's session-expiry ceiling is
+                already in the past.
         """
         client = self._client
         origin_domain = await client._resolve_current_domain(store_options)
@@ -282,17 +297,24 @@ async def verify(
 
     # ------------------------------------------------------------- internals
 
-    async def _build_magic_link_auth_params(
+    def _prepare_magic_link_start(
         self,
         options: StartPasswordlessEmailOptions,
         origin_domain: str,
         store_options: Optional[dict[str, Any]],
-    ) -> dict[str, Any]:
+    ) -> tuple[dict[str, Any], tuple[str, TransactionData]]:
         """
-        Build the magic-link ``authParams`` and persist the transaction.
+        Build the magic-link ``authParams`` and the transaction to persist.
 
         The SDK owns ``redirect_uri`` / ``response_type`` / ``state``; caller
         ``auth_params`` may only contribute non-reserved passthrough keys.
+        Persisting the transaction is the caller's job, deferred until after
+        ``POST /passwordless/start`` succeeds — a failed start must not leave a
+        transaction (and its cookie) behind.
+
+        Raises:
+            MissingRequiredArgumentError: When no ``redirect_uri`` is configured
+                on the client, or ``store_options`` is not provided.
         """
         client = self._client
 
@@ -302,52 +324,36 @@ async def _build_magic_link_auth_params(
 
         auth_params = self._sanitize_caller_auth_params(options.auth_params)
 
-        # Required to persist the transaction cookie; checked after input
-        # validation so bad auth_params / missing redirect_uri surface first.
         if store_options is None:
             raise MissingRequiredArgumentError("store_options")
 
         # Auth0 echoes `state` back unvalidated on this flow — it does not
         # compare it server-side, and the clicked link's query string can
         # overwrite whatever was originally stored. This SDK's single-use,
-        # state-keyed transaction (below) plus the exact-match, SDK-owned
+        # state-keyed transaction plus the exact-match, SDK-owned
         # `redirect_uri` is therefore the *only* CSRF/authorization-code-
         # interception control on magic link; the server provides none.
         # Never make `state`/`redirect_uri` caller-overridable.
         state = PKCE.generate_random_string(32)
         auth_params["redirect_uri"] = redirect_uri
         auth_params["response_type"] = "code"
         auth_params["state"] = state
-        # Magic link is email-only, so the email scope is always appropriate.
         auth_params.setdefault("scope", DEFAULT_PASSWORDLESS_EMAIL_SCOPE)
         # A caller-supplied scope replaces the default wholesale, so `openid`
         # is re-injected rather than trusted: without it Auth0 returns no ID
-        # token, and the callback only demands one when an organization was
-        # requested — leaving a session with no signature-verified claims.
+        # token and the callback never demands one, leaving a session with no
+        # signature-verified claims.
         auth_params["scope"] = self._ensure_openid_scope(auth_params["scope"])
-        if options.organization:
-            auth_params["organization"] = options.organization
-
-        # Magic link uses a plain authorization-code exchange (no PKCE), so the
-        # transaction stores no code_verifier. Single-use is enforced by
-        # transaction deletion on the callback; remove_if_expires signals the
-        # store to drop the transaction once expired. Its effective lifetime is
-        # the store's configured duration, not a fixed value set here.
+
         transaction_data = TransactionData(
             code_verifier=None,
             audience=auth_params.get("audience"),
             redirect_uri=redirect_uri,
             domain=origin_domain,
-            organization=options.organization,
-        )
-        await client._transaction_store.set(
-            f"{client._transaction_identifier}:{state}",
-            transaction_data,
-            remove_if_expires=True,
-            options=store_options,
         )
+        tx_key = f"{client._transaction_identifier}:{state}"
 
-        return auth_params
+        return auth_params, (tx_key, transaction_data)
 
     @staticmethod
     def _ensure_openid_scope(scope: str) -> str:

src/auth0_server_python/auth_types/__init__.py

@@ -700,7 +700,8 @@ class MfaTokenContext(BaseModel):
 # authParams keys the SDK owns and MUST NOT let a caller override for the
 # magic-link flow. A caller-controlled redirect_uri/state would allow the
 # emailed code+state to be redirected to an attacker (authorization-code
-# interception); the PKCE/nonce/response_type keys are protocol-controlled.
+# interception); the PKCE/nonce/response_type keys are reserved (not set by
+# the SDK for magic link, but never caller-overridable either).
 # Mirrors nextjs-auth0's MAGIC_LINK_EXCLUDED_PARAMS / INTERNAL_AUTHORIZE_PARAMS.
 # Kept explicit so a rejected override gets a precise "set by the SDK" message.
 PASSWORDLESS_RESERVED_AUTH_PARAMS = frozenset(
@@ -742,14 +743,16 @@ class MfaTokenContext(BaseModel):
 class _StartPasswordlessBase(BaseModel):
     """Shared options for starting a passwordless flow."""
 
+    # Unknown keys raise rather than being silently ignored, so a caller
+    # passing an unsupported kwarg is told, not quietly dropped.
+    model_config = ConfigDict(extra="forbid")
+
     # BCP 47 tag (e.g. "fr", "en-US"). Forwarded as x-request-language to
     # localise the email/SMS template.
     language: Optional[str] = None
     # Extra params forwarded to /passwordless/start. SDK-owned keys
     # (PASSWORDLESS_RESERVED_AUTH_PARAMS) are stripped in the client.
     auth_params: Optional[dict[str, Any]] = None
-    # Organization id or name; validated against ID token claims on verify.
-    organization: Optional[str] = None
     # Attempted solution to a captcha challenge, when the tenant requires one.
     captcha: Optional[str] = None
     # End-user client IP, relayed to Auth0 as `auth0-forwarded-for` so brute-force
@@ -803,7 +806,7 @@ class VerifyPasswordlessOtpOptions(BaseModel):
     """
 
     # Unknown keys raise rather than being silently ignored, so a caller
-    # passing the removed `organization` kwarg is told, not quietly dropped.
+    # passing an unsupported kwarg is told, not quietly dropped.
     model_config = ConfigDict(extra="forbid")
 
     connection: PasswordlessConnection
@@ -814,9 +817,6 @@ class VerifyPasswordlessOtpOptions(BaseModel):
     phone_number: Optional[str] = None
     scope: Optional[str] = None
     audience: Optional[str] = None
-    # No `organization` field: Auth0 ignores it for the OTP grant (verified
-    # against auth0-server), so accepting it would silently never succeed.
-    # Use magic link's `organization` instead.
     # End-user client IP, relayed to Auth0 as `auth0-forwarded-for` on the OTP
     # token exchange so brute-force protection keys on the real user, not the
     # app server. Honored only for confidential clients with "Trust Token