[rmad17]

Summary

Adds passkey signup and login to AuthClient, including identifier verification at signup. When a database connection requires email or phone verification, the signup challenge returns verification_required and signin_with_passkey() accepts the codes the user received.

The new methods pass their arguments straight through to ServerClient in auth0-server-python, following the existing custom token exchange methods. The SDK does not mount passkey routes. Apps add their own routes, as shown in the new guide.

Changes

• AuthClient (src/auth0_fastapi/auth/auth_client.py): three methods added at the end of the class. Each forwards every argument by keyword to ServerClient.
  • passkey_signup_challenge() accepts user_profile, connection, organization, user_metadata, delivery_method ("text" or "voice"), client_ip and store_options. The response includes verification_required when the connection requires verification.
  • passkey_login_challenge() accepts connection, organization, client_ip and store_options.
  • signin_with_passkey() exchanges the credential for tokens and establishes the session for both signup and login. It accepts optional verification codes, connection, organization, scope, audience, dpop_key, client_ip and store_options.
  • client_ip is forwarded as the auth0-forwarded-for header. The SDK does not derive it from the request.
• Errors (src/auth0_fastapi/errors/__init__.py): re-exports PasskeyError and PasskeyErrorCode. auth0_exception_handler returns a PasskeyError with status_code 429 as HTTP 429 and sets Retry-After when Auth0 sent one. Any other PasskeyError that carries an Auth0 status between 400 and 599 is returned with that same status. A failure with no Auth0 response, such as a network error, stays 400. The response body still carries only error and message, so auth_session never appears in a generic error response.
• Dependency: raises the minimum auth0-server-python to 1.0.0b20 in pyproject.toml, requirements.txt and poetry.lock.
• Docs:
  • New examples/Passkeys.md covers:
    • signup and login, with the browser-side helpers for both credentials
    • identifier verification: requirements, collecting codes before creating the credential, the retry loop, retryable vs terminal errors, rate-limit retries and resending codes
    • security considerations, including bounded request models for the sign-in body, forwarding a trusted client IP, and treating auth_session and codes as credentials
    • error-to-status mapping, and completing MFA after a passkey sign-in with the matching routes
    • organizations and DPoP
  • README.md gains a Passkeys feature bullet and a Passkeys section that links to the guide.

Testing

• test_auth_client.py: new TestPasskey class with 11 tests. They cover:
  • argument forwarding and defaults for all three methods, including client_ip and a login credential
  • dpop_key passed through as the same object
  • retryable and terminal PasskeyError propagation, with auth_session and verification_required intact
  • rate-limit propagation (status_code, retry_after) from both challenges
  • InvalidArgumentError for an unknown verification key
• test_errors.py (new, 14 tests): 429 with and without Retry-After, Auth0 statuses relaybody leaves out auth_session, and a missing or non-error status staying at 400.
• test_passkey_http.py (new, 17 tests): runs the real AuthClient and ServerClient against a mocked Auth0 (httpx.MockTransport), so a renamed ServerClient keyword fails them. They cover:
  • the challenge and token requests, including the auth0-forwarded-for header and request
  • 429 handling, the wrong-code retry, organization claim checks and DPoP
  • the stored session after sign-in
  • the MFA path: sign-in stopping at mfa_required, mfa.verify with persist creating the session, and a rejected code leaving none
• Full suite: 173 passed against auth0-server-python 1.0.0b20 on Python 3.9, 3.10 and 3.12.
• The guide's Python routes were run against a mocked Auth0 and its JavaScript was syntax-checked and run with stubbed browser APIs. This is not part of the test suite.

Tested flows

#	Flow	Scenario
1	Happy path	Passkey signup (register) and passkey login
2	Organization	Passkey signup and login with organization set
3	Global MFA	Passkey sign-in with tenant-wide MFA required
4	Step-up MFA	Passkey sign-in followed by an MFA challenge for elevated access
5	DPoP	Passkey sign-in with dpop_key, issuing DPoP-bound tokens

[nandan-bhat]

Question on the other PasskeyError cases. An Auth0 5xx, a gateway error or a network failure also reaches the browser as 400 (the table in the guide says the same). For the user, a temporary Auth0 outage then looks like a bad request.

Should we return 502 when status_code is None or 500 and above? I feel it is more correct than 400.

[rmad17]

I would agree that 400 is not correct status code but status code is the platforms call which SDK should not modify.