Skip to content

Extending litestar-auth

User model

Subclass the provided User (or follow the same column contract) and point LitestarAuthConfig.user_model at your class. Keep sensitive fields out of public schemas via user_read_schema / msgspec structs.

User manager

Subclass BaseUserManager to implement lifecycle hooks and custom rules. See the dedicated Hooks page for when each hook runs and timing considerations (on_after_forgot_password).

The plugin injects a request-scoped manager built with your user_db_factory, backends, and optional password_validator.

Constructor compatibility

If your manager needs password_validator or login_identifier, either accept them in __init__ or set class attributes accepts_password_validator / accepts_login_identifier so the plugin can detect support.

Custom factory

Set user_manager_factory on LitestarAuthConfig for full control over manager construction (must match the UserManagerFactory contract).

Controllers and DTOs

Factory functions such as create_auth_controller live in litestar_auth.controllers. The plugin calls them internally based on flags like include_register. For advanced scenarios you can:

  • Reuse the built-in auth lifecycle DTOs from litestar_auth.payloads: LoginCredentials, RefreshTokenRequest, ForgotPassword, ResetPassword, RequestVerifyToken, VerifyToken, and the TOTP request/response structs. These are the names the generated OpenAPI publishes for the default controllers.
  • Provide custom msgspec schemas via litestar_auth.schemas or your own structs wired through user_create_schema, user_update_schema, and user_read_schema for registration and user CRUD surfaces.
  • Fork behavior inside your manager rather than replacing controllers first.

If an app-owned user_create_schema or user_update_schema keeps a password field, import UserPasswordField from litestar_auth.schemas instead of duplicating msgspec.Meta(min_length=12, max_length=128) locally:

import msgspec

from litestar_auth.schemas import UserPasswordField


class ExtendedUserCreate(msgspec.Struct):
    email: str
    password: UserPasswordField
    display_name: str

That alias only keeps the schema metadata aligned with the built-in UserCreate and UserUpdate structs. The default runtime validator still enforces password length through require_password_length, and password_validator_factory remains the extension point for stricter runtime policy.

user_create_schema, user_update_schema, and user_read_schema do not replace the built-in login, verification, reset-password, refresh, or TOTP request payloads. If you need different field names for those routes, mount or wrap the relevant controller factory instead of expecting login_identifier or user_*_schema to rename identifier, email, token, refresh_token, pending_token, or code.

Multiple backends

Additional backends after the first are exposed under /auth/{backend_name}/.... Use distinct name values on each AuthenticationBackend.

Rate limits

Pass rate_limit_config to apply throttles to sensitive endpoints without ad hoc middleware. See Rate limiting.