# litestar-auth

Authentication and authorization for [Litestar](https://litestar.dev/) 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](https://litestar.dev/) 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, cookie, or API key) with a **strategy** (JWT, database, Redis, or API-key validation).
- **User manager** — `BaseUserManager` centralizes password hashing, tokens, hooks, and session invalidation.
- **Role contract** — bundled and custom SQLAlchemy models store role membership in `role` / `user_role` tables; HTTP responses, managers, and guards still use one normalized flat `roles` collection.
- **Role administration** — when the plugin has `session_maker` plus a relational role-capable SQLAlchemy `user_model`, it registers `litestar roles` for operator workflows, and apps can opt into `litestar_auth.contrib.role_admin` for an HTTP admin controller with the same flat `user.roles` boundary.
- **User DTOs** — the built-in register/verify/reset/users responses expose normalized `roles`; self-service updates keep those fields privileged by default.
- **Guards** — `is_authenticated`, `is_active`, `is_verified`, `is_superuser`, plus `has_any_role(...)` / `has_all_roles(...)` for route-level authorization over flat normalized roles.
- **Optional** — TOTP, OAuth login and account linking, auth endpoint rate limits.

## Documentation map

| Section | Start here |
| ------- | ---------- |
| Install & extras | [Installation](install.md) |
| First working app | [Quickstart](quickstart.md) |
| Mental model | [Architecture](concepts/architecture.md), [Backends](concepts/backends.md), [Request lifecycle](concepts/request_lifecycle.md) |
| How-to guides | [Security](guides/security.md), [Registration](guides/registration.md), [OAuth](guides/oauth.md), [TOTP](guides/totp.md), [Rate limiting](guides/rate_limiting.md), [Role management CLI](guides/roles_cli.md), [HTTP role administration](guides/role_admin_http.md), [Testing plugin-backed apps](guides/testing.md), [Hooks](guides/hooks.md), [Extending](guides/extending.md) |
| Recipes & examples | [Cookie + CSRF](cookbook/cookie_csrf.md), [Refresh cookie](cookbook/refresh_cookie.md), [OAuth account linking](cookbook/oauth_associate.md), [Custom User model with OAuth](cookbook/custom_user_oauth.md), [API keys](cookbook/api_keys.md), [Custom role administration controller](cookbook/role_admin_controller.md), [Testing custom role admin](cookbook/role_admin_tests.md) |
| Moving from fastapi-users | [Concept mapping](guides/from_fastapi_users.md) (optional) |
| HTTP reference | [HTTP API](http_api.md), [Errors](errors.md) |
| Config & ops | [Configuration index](configuration.md) (split topics: [Backends](configuration/backends.md), [OAuth](configuration/oauth.md), [TOTP](configuration/totp.md), …), [Security overview](security.md), [Deployment](deployment.md) |
| Python API | [Package](api/package.md) and subpages under **Python API** in the nav |
| Project | [Roadmap](roadmap.md), [Contributing](contributing.md), [Test suite README](https://github.com/ZYLVEXT/litestar-auth/blob/main/tests/README.md) |

!!! note "Tooling and AI agents"
    Stable entry points for navigation and API surface: this page (documentation map), [HTTP API](http_api.md), [Package overview](api/package.md), and the authoritative `__all__` in `litestar_auth/__init__.py` on your installed version. Maintainer workflows and verification commands are in [Contributing](contributing.md); the repo-internal test pyramid and marker guide lives in the [test suite README](https://github.com/ZYLVEXT/litestar-auth/blob/main/tests/README.md).

!!! note "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

```python
--8<-- "docs/snippets/home_quick_peek.py"
```

See [Quickstart](quickstart.md) for a runnable pattern with the default `User` model and secrets.
