Passwordless Authentication
Passwordless login through pluggable handlers such as email magic links and passkeys.
Views
- class auth_kit.passwordless.views.PasswordlessInitiateView(**kwargs)
Bases:
GenericAPIViewInitiate passwordless authentication.
Accepts handler-specific input (e.g., email for magic link, optional email for WebAuthn) and starts the passwordless flow.
- get_serializer_class() type[Serializer]
Get serializer class from handler.
- Returns:
Combined request serializer class
- permission_classes = (<class 'rest_framework.permissions.AllowAny'>,)
- post(request: Request, *args: Any, **kwargs: Any) Response
Initiate passwordless authentication flow.
- Parameters:
request – HTTP request with handler-specific data
- Returns:
Response with handler-specific result
- throttle_scope = 'auth_kit'
- class auth_kit.passwordless.views.PasswordlessVerifyView(**kwargs: Any)
Bases:
LoginViewVerify passwordless authentication.
Accepts handler-specific verification data and completes the passwordless authentication flow. Returns either login tokens directly or MFA first-step response depending on the handler’s IS_MULTI_FACTOR flag and USE_MFA setting.
- get_serializer_class() type[Serializer]
Get serializer class from handler.
- Returns:
Combined verify serializer class
- permission_classes = (<class 'rest_framework.permissions.AllowAny'>,)
- post(request: Request, *args: Any, **kwargs: Any) Response
Verify passwordless authentication and return tokens.
- Parameters:
request – HTTP request with verification data
- Returns:
Response with auth tokens or MFA first-step data
- throttle_scope = 'auth_kit'
Serializers
Login Serializers
- auth_kit.passwordless.serializers.login.get_passwordless_verify_serializer(handler_class: type[PasswordlessBaseHandler]) type[Serializer]
Get combined serializer for passwordless verify step.
Combines the handler’s verify serializer with the appropriate response serializer (login tokens or MFA first-step response).
- Parameters:
handler_class – The passwordless handler class
- Returns:
Combined serializer class for the verify step
- auth_kit.passwordless.serializers.login.get_passwordless_final_response_serializer(handler_class: type[PasswordlessBaseHandler]) type[Serializer]
Get the final response serializer for passwordless verification.
This is the extension point for MFA interception. If the handler declares IS_MULTI_FACTOR=True, returns login tokens directly. Otherwise, if MFA is enabled, returns MFA first-step response (ephemeral token + method info) instead.
- Parameters:
handler_class – The passwordless handler class
- Returns:
Response serializer class
- class auth_kit.passwordless.serializers.login.RequireActiveUserMixin(*args, **kwargs)
Bases:
SerializerReject a resolved user whose account has been deactivated.
Password login goes through
authenticate(), which applies this check. Passwordless resolves the user from a token or credential instead, so it has to apply the check itself. Sits between the handler’s verify serializer and the response serializer so that a deactivated user is rejected before any token is minted.
Email Magic Link Serializers
- class auth_kit.passwordless.serializers.email_link.EmailLinkInitiateSerializer(*args, **kwargs)
Bases:
SerializerSerializer for the email magic link initiate step.
Accepts the address to send the magic link to and returns the confirmation message.
- email
Email address to send the magic link to
- detail
Confirmation message
- class auth_kit.passwordless.serializers.email_link.EmailLinkVerifySerializer(*args, **kwargs)
Bases:
SerializerSerializer for verifying email magic link tokens.
Accepts the token from the magic link and validates it.
- token
The magic link token from the email
- validate(attrs: dict[str, Any]) dict[str, Any]
Validate the magic link token.
Decodes and verifies the ephemeral token, extracting the user identity.
- Parameters:
attrs – Input attributes dictionary
- Returns:
Validated attributes with user in context
- Raises:
ValidationError – If token is invalid or expired
WebAuthn Serializers
- class auth_kit.passwordless.serializers.webauthn.WebAuthnInitiateSerializer(*args, **kwargs)
Bases:
WebAuthnAuthenticationOptionsSerializerSerializer for the WebAuthn initiate step.
Optionally accepts an email to filter credentials for non-discoverable (security key) flows. If omitted, discoverable credential (passkey) flow is used. Inherits the ceremony options that make up the response.
- email
Optional email to look up user credentials
- class auth_kit.passwordless.serializers.webauthn.WebAuthnVerifySerializer(*args, **kwargs)
Bases:
SerializerSerializer for verifying WebAuthn authentication assertions.
Accepts the credential assertion response from the browser’s navigator.credentials.get() API.
- credential
The assertion response JSON from the browser
- session_id
Opaque session token from the initiate step
- validate(attrs: dict[str, Any]) dict[str, Any]
Verify the WebAuthn assertion.
Validates the assertion against stored credentials and returns the authenticated user.
- Parameters:
attrs – Input attributes dictionary
- Returns:
Validated attributes with user in context
- Raises:
ValidationError – If assertion verification fails
Handlers
Base Handler
- class auth_kit.passwordless.handlers.base.PasswordlessBaseHandler
Bases:
objectBase class for all passwordless authentication handlers.
Provides the interface for passwordless login flows. Subclasses must implement method-specific behavior for initiating and verifying passwordless authentication.
Subclasses must define a NAME (snake_case method identifier) and optionally customize DISPLAY_NAME (human-readable name) and IS_MULTI_FACTOR flag (whether the method provides multi-factor assurance, allowing MFA to be skipped after verification).
- IS_MULTI_FACTOR = False
- NAME = ''
- classmethod get_initiate_serializer_class() type[Serializer]
Get serializer class for the initiate step.
A single serializer carries both directions: write-only fields are the accepted input, read-only fields are the returned payload.
- Returns:
Serializer class for the initiate step
- classmethod get_verify_serializer_class() type[Serializer]
Get serializer class for the verify step.
- Returns:
Serializer class for the verify step
- classmethod handle_initiate(validated_data: dict[str, Any], context: dict[str, Any]) dict[str, Any]
Process the initiate step.
Called after the initiate serializer validates input. Should initiate the passwordless flow (e.g., send magic link, generate challenge) and return data for the response.
- Parameters:
validated_data – Validated initiate data
context – Serializer context (includes ‘request’)
- Returns:
Response data dictionary
- classmethod handle_verify(validated_data: dict[str, Any], context: dict[str, Any]) AbstractBaseUser
Process the verification step.
Called after the verify serializer validates input. Should verify the passwordless credential and return the authenticated user.
- Parameters:
validated_data – Validated verification data
context – Serializer context (includes ‘request’)
- Returns:
Authenticated user instance
- class auth_kit.passwordless.handlers.base.PasswordlessHandlerRegistry
Bases:
objectRegistry for managing available passwordless handlers.
Provides centralized registration and retrieval of passwordless handler classes. Handlers are automatically imported when first accessed.
- Class Attributes:
_handlers: Dictionary mapping method names to handler classes imported_handler: Flag tracking whether handlers have been imported
- classmethod get_handler_class(handler_name: str) type[PasswordlessBaseHandler]
Get handler class by method name.
- Parameters:
handler_name – Name of the passwordless method
- Returns:
Handler class for the method
- Raises:
ValueError – If method name is not supported
- classmethod get_handlers() dict[str, type[PasswordlessBaseHandler]]
Get all registered handlers.
- Returns:
Dictionary mapping names to handler classes
- imported_handler = False
- classmethod list_handler_names() list[str]
Get list of all registered handler names.
- Returns:
List of handler names
- classmethod register(handler_class: type[PasswordlessBaseHandler]) None
Register a handler class.
- Parameters:
handler_class – Handler class to register
Email Magic Link Handler
- class auth_kit.passwordless.handlers.email_link.EmailLinkHandler
Passwordless authentication via email magic link.
Sends a time-limited token via email that allows the user to authenticate without a password. Since this only proves access to the email inbox (single factor), MFA is still applied after verification if configured.
- IS_MULTI_FACTOR = False
- NAME = 'email'
- classmethod get_initiate_serializer_class() type[Serializer]
Get serializer for the email initiate step.
- classmethod get_verify_serializer_class() type[Serializer]
Get serializer for the email verify step.
- classmethod handle_initiate(validated_data: dict[str, Any], context: dict[str, Any]) dict[str, Any]
Send magic link email to the user.
Looks up the user by email and sends a magic link. For security, always returns success even if the email doesn’t exist (prevents email enumeration).
- Parameters:
validated_data – Contains ‘email’ field
context – Serializer context
- Returns:
Detail message dictionary
- classmethod handle_verify(validated_data: dict[str, Any], context: dict[str, Any]) Any
Verify the magic link token.
The actual token validation is done in the serializer’s validate() method, which sets context[‘user’].
- Parameters:
validated_data – Validated data from serializer
context – Serializer context with ‘user’ key
- Returns:
Authenticated user instance
WebAuthn Handler
- class auth_kit.passwordless.handlers.webauthn.WebAuthnHandler
Passwordless authentication via WebAuthn (passkeys and security keys).
Supports two flows: - Passkey (discoverable): No email needed, browser prompts for credential - Security key (non-discoverable): Email provided to filter allowed credentials
Since WebAuthn inherently provides multi-factor assurance (something you have + something you are/know), MFA is skipped after successful verification.
- IS_MULTI_FACTOR = True
- NAME = 'webauthn'
- classmethod get_initiate_serializer_class() type[Serializer]
Get serializer for the WebAuthn initiate step.
- classmethod get_verify_serializer_class() type[Serializer]
Get serializer for the WebAuthn verify step.
- classmethod handle_initiate(validated_data: dict[str, Any], context: dict[str, Any]) dict[str, Any]
Generate WebAuthn authentication options.
If email is provided, looks up the user and filters allowed credentials. Otherwise, uses discoverable credential flow.
- Parameters:
validated_data – May contain ‘email’ field
context – Serializer context
- Returns:
Authentication options dictionary with challenge
- classmethod handle_verify(validated_data: dict[str, Any], context: dict[str, Any]) AbstractBaseUser
Verify WebAuthn assertion.
The actual assertion verification is done in the serializer’s validate() method, which sets context[‘user’].
- Parameters:
validated_data – Validated data from serializer
context – Serializer context with ‘user’ key
- Returns:
Authenticated user instance
Services
Token Services
- class auth_kit.passwordless.services.token.PasswordlessEphemeralTokenService
Bases:
objectService for managing ephemeral tokens in passwordless authentication.
Provides secure token generation and validation with time-based expiry, user binding, single-use enforcement, and password-change invalidation to prevent token misuse and replay attacks. Used primarily for email magic link flows.
- Class Attributes:
KEY_SALT: Salt for HMAC token generation
- KEY_SALT = 'auth_kit.passwordless.EphemeralTokenService'
- class auth_kit.passwordless.services.token.PasswordlessSignupTokenService
Bases:
objectService for magic link tokens issued to addresses with no account yet.
The ephemeral token service binds a token to an existing user row, which signup cannot do. These tokens are random and opaque, with the pending email held server side, so hitting the request endpoint never creates a user. The account is only made once the link is clicked.
- Class Attributes:
CACHE_PREFIX: Cache key prefix for pending signups
- CACHE_PREFIX = 'passwordless:signup:'
- auth_kit.passwordless.services.token.passwordless_token_service = <auth_kit.passwordless.services.token.PasswordlessEphemeralTokenService object>
Service for managing ephemeral tokens in passwordless authentication.
Provides secure token generation and validation with time-based expiry, user binding, single-use enforcement, and password-change invalidation to prevent token misuse and replay attacks. Used primarily for email magic link flows.
- Class Attributes:
KEY_SALT: Salt for HMAC token generation
- auth_kit.passwordless.services.token.passwordless_signup_token_service = <auth_kit.passwordless.services.token.PasswordlessSignupTokenService object>
Service for magic link tokens issued to addresses with no account yet.
The ephemeral token service binds a token to an existing user row, which signup cannot do. These tokens are random and opaque, with the pending email held server side, so hitting the request endpoint never creates a user. The account is only made once the link is clicked.
- Class Attributes:
CACHE_PREFIX: Cache key prefix for pending signups
Settings
- class auth_kit.passwordless.passwordless_settings.PasswordlessSetting
Default passwordless settings configuration for Auth Kit.
Provides all configurable options for passwordless authentication including handler configuration, token expiry, and view/serializer classes.
- PASSWORDLESS_HANDLERS: list[type[PasswordlessBaseHandler]] = ['auth_kit.passwordless.handlers.email_link.EmailLinkHandler']
- PASSWORDLESS_INITIATE_VIEW: type[PasswordlessInitiateView] = 'auth_kit.passwordless.views.PasswordlessInitiateView'
- PASSWORDLESS_VERIFY_VIEW: type[PasswordlessVerifyView] = 'auth_kit.passwordless.views.PasswordlessVerifyView'