Passwordless Authentication

Passwordless login through pluggable handlers such as email magic links and passkeys.

Views

class auth_kit.passwordless.views.PasswordlessInitiateView(**kwargs)

Bases: GenericAPIView

Initiate passwordless authentication.

Accepts handler-specific input (e.g., email for magic link, optional email for WebAuthn) and starts the passwordless flow.

authentication_classes: list[Any] = []
get_handler_class() → Any

Get the handler class from URL kwargs.

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: LoginView

Verify 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.

authentication_classes: list[Any] = []
get_handler_class() → Any

Get the handler class from URL kwargs.

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: Serializer

Reject 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.

validate(attrs: dict[str, Any]) → dict[str, Any]

Run the handler’s validation, then require an active user.

Parameters:

attrs – Input attributes dictionary

Returns:

Validated attributes

Raises:

ValidationError – If the resolved user is inactive

WebAuthn Serializers

class auth_kit.passwordless.serializers.webauthn.WebAuthnInitiateSerializer(*args, **kwargs)

Bases: WebAuthnAuthenticationOptionsSerializer

Serializer 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: Serializer

Serializer 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: object

Base 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).

DISPLAY_NAME: str = ''
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: object

Registry 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

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.

DISPLAY_NAME: str | _StrPromise = 'Passkey / Security Key'
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: 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

KEY_SALT = 'auth_kit.passwordless.EphemeralTokenService'
check_token(token: str) → User | None

Validate and decode ephemeral token.

Verifies token signature, expiry time, single-use status, and extracts user information from valid tokens.

Parameters:

token – Ephemeral token string to validate

Returns:

User instance if valid, None if invalid

make_token(user: User) → str

Generate ephemeral token for user.

Creates a time-limited, single-use token that binds user identity for secure passwordless authentication.

Parameters:

user – User instance for token generation

Returns:

Signed ephemeral token string

class auth_kit.passwordless.services.token.PasswordlessSignupTokenService

Bases: 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

CACHE_PREFIX = 'passwordless:signup:'
consume_token(token: str) → str | None

Redeem a signup token and return its pending email.

The token is deleted on read, so a link works exactly once.

Parameters:

token – Signup token string to redeem

Returns:

Pending email if the token is valid, None otherwise

make_token(email: str) → str

Issue a signup token for an address with no account.

Parameters:

email – Address the magic link will be sent to

Returns:

Opaque single-use token string

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_EMAIL_HTML_TEMPLATE: str = 'auth_kit/passwordless/email/magic_link.html'
PASSWORDLESS_EMAIL_PLAIN_TEMPLATE: str = 'auth_kit/passwordless/email/magic_link.txt'
PASSWORDLESS_EMAIL_SIGNUP: bool = False
PASSWORDLESS_EMAIL_SUBJECT: str = 'Your login link'
PASSWORDLESS_EPHEMERAL_TOKEN_EXPIRY: int = 900
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'
user_settings: dict[str, Any] = {}