authwarden¶
A production-grade, pluggable authentication library for FastAPI.
JWT auth, OAuth2 across 8 providers, MFA, RBAC, and full flow flexibility — behind a single facade you mount into any FastAPI app.
pip install authwarden
This site is the complete reference. If you just want to get something running in two minutes, start with the README instead — come back here when you need a specific config field, flow detail, or customization pattern.
What's covered here¶
- Installation and Quickstart — same as the README, slightly more detail
- Configuration Reference — every
WardenConfigfield, what it does, and its default - Core Concepts — the
AuthWardenfacade, theAbstractUserStoreprotocol, theUserInDBmodel - Authentication Flows — every flow, with real request/response examples
- MFA and Permissions — TOTP setup and RBAC
- OAuth / Social Login — all 8 providers, account linking, Apple's special handling
- Notifications — every email/SMS backend and how to write your own
- Security — what's protected by default and why
- API Reference — every endpoint, every status code
- Customization Guide — subclassing the user model, writing a database adapter, overriding templates
Design philosophy¶
authwarden is built around Protocols, not base classes. Almost everything — the user store, the email backend, the SMS backend, the notification service — can be swapped for your own implementation without touching the library's internals. You don't inherit from anything; you just implement the methods the protocol expects.
This means:
- Use any database — the
AbstractUserStoreprotocol already works with SQLAlchemy, MongoDB/Beanie, SQLModel, or Tortoise via a thin adapter you write - Use any email or SMS provider — built-in backends exist for the common ones, but writing your own is a single class with one method
- Extend the user model with your own fields — via
extra_dataor full subclassing, no migration required for the simple case