Skip to content

litestar-auth

Authentication and authorization for Litestar applications: registration, login, email verification, password reset, OAuth2, TOTP (2FA), guards, and optional rate limiting. Everything is wired as a native plugin with transport + strategy composition.

Who it is for

Teams building on Litestar who need registration, login, verification, password reset, OAuth, optional 2FA, and route guards without re-implementing security-sensitive flows from scratch.

Features

  • Plugin entry point — LitestarAuth registers middleware, DI, controllers, and exception handling from one config object.
  • Backends — AuthenticationBackend combines a transport (Bearer or Cookie) with a strategy (JWT, database, or Redis tokens).
  • User manager — BaseUserManager centralizes password hashing, tokens, hooks, and session invalidation.
  • Guards — is_authenticated, is_active, is_verified, is_superuser for route-level authorization.
  • Optional — TOTP, OAuth login and account linking, auth endpoint rate limits.

Documentation map

Section Start here
Install & extras Installation
First working app Quickstart
Mental model Architecture, Backends, Request lifecycle
How-to guides Security, Registration, OAuth, TOTP, Rate limiting, Hooks, Extending
Moving from fastapi-users Concept mapping (optional)
HTTP reference HTTP API, Errors
Config & ops Configuration, Security overview, Deployment
Python API Package and subpages under Python API in the nav
Project Roadmap, Contributing

Tooling and AI agents

Stable entry points for navigation and API surface: this page (documentation map), HTTP API, Package overview, and the authoritative __all__ in litestar_auth/__init__.py on your installed version. Maintainer workflows and verification commands are in Contributing.

Email and UI

The library does not send email or ship a UI. Use hooks on BaseUserManager to trigger your mailer or jobs.

Quick peek

"""Home-page quick peek: plugin wiring (placeholders). Included via pymdownx.snippets."""

from litestar import Litestar
from litestar_auth import LitestarAuth, LitestarAuthConfig
from litestar_auth.authentication.backend import AuthenticationBackend
from litestar_auth.authentication.strategy import JWTStrategy
from litestar_auth.authentication.transport import BearerTransport

config = LitestarAuthConfig(
    backends=(
        AuthenticationBackend(
            name="jwt",
            transport=BearerTransport(),
            strategy=JWTStrategy(secret="...", subject_decoder=YourIdType),
        ),
    ),
    user_model=YourUser,
    user_manager_class=YourUserManager,
    session_maker=async_session_factory,
)
app = Litestar(plugins=[LitestarAuth(config)])

See Quickstart for a runnable pattern with the default User model and secrets.