fastapi-users

FastAPI Users is a drop-in users management layer for FastAPI applications. Rather than hand-rolling registration, login, password reset, and email verification endpoints for every new project, it ships pre-built APIRouters for each of these flows, backed by pluggable storage adapters (SQLAlchemy async ORM or Beanie/MongoDB) and pluggable authentication strategies (JWT, database-backed sessions, or Redis).

The design leans on FastAPI’s own dependency-injection system: a FastAPIUsers instance exposes current_user as a dependency callable that route handlers can require, with parameters for active/verified/superuser gating baked in. User models and schemas are Pydantic-based and meant to be subclassed, so teams can add custom fields without forking the library’s core logic. OAuth2 social login (Google, GitHub, and any provider httpx-oauth supports) is available as an optional extra with the same router-generation pattern.

The project is explicitly in maintenance mode as of 2026 — the maintainers are building a successor authentication toolkit and have stated FastAPI Users will continue to receive security and dependency updates but no new features. It remains a stable, widely-used choice for teams that need conventional auth wired up quickly and don’t need bleeding-edge additions.

What You Get

• Pre-built APIRouters for register, login/logout, password reset, and email verification flows that mount directly onto a FastAPI app
• A current_user dependency factory with built-in active/verified/superuser gating for protecting routes
• Pluggable database adapters — SQLAlchemy (async) and Beanie/MongoDB — via separate optional-dependency packages
• Multiple authentication backends out of the box: JWT bearer tokens, database-backed session tokens, and Redis-backed sessions, mixable via named AuthenticationBackend instances
• Optional OAuth2 social login and account-association routers built on httpx-oauth, supporting any provider that library covers
• Pydantic-based user schemas designed for subclassing, so custom profile fields extend the base model without touching library internals

Common Use Cases

• Bootstrapping auth for a new FastAPI backend without hand-writing registration/login/reset endpoints
• Adding social login (Google, GitHub, etc.) to an existing FastAPI app via the OAuth2 router
• Gating specific routes behind active-user, verified-user, or superuser dependency checks
• Swapping between JWT and server-side session authentication without changing route-handler code
• Extending the base user model with app-specific profile fields while keeping the built-in auth flows

Under The Hood

Architecture The library is organized around a small set of composable layers: fastapi_users/manager.py defines BaseUserManager, which owns the business logic for creating, authenticating, and resetting users against a BaseUserDatabase adapter (fastapi_users/db/); fastapi_users/authentication/ defines AuthenticationBackend and Authenticator, which combine a Transport (how the token travels — header or cookie) with a Strategy (how the token is validated — JWT, DB, or Redis) and expose a current_user dependency callable built with makefun.with_signature so FastAPI’s dependency introspection sees the right parameter signature at runtime; and fastapi_users/router/ holds the actual route-generation functions (get_auth_router, get_register_router, etc.) that the top-level FastAPIUsers class in fastapi_users/fastapi_users.py wires together. This separation means swapping a database backend or an authentication strategy touches one adapter, not the router or manager code, and a change to the core UserManager abstraction would ripple through every router since they all depend on UserManagerDependency.

Tech Stack Built on Python 3.10+ and FastAPI itself as the only hard web-framework dependency, with pwdlib (Argon2 + bcrypt hashers) for password hashing, pyjwt for JWT encode/decode, python-multipart for form parsing, and makefun for the dynamic-signature dependency trick. Database support is split into separate optional packages (fastapi-users-db-sqlalchemy, fastapi-users-db-beanie) rather than bundled, and OAuth support similarly depends on the optional httpx-oauth extra. Redis session strategy pulls in the redis client as an extra. Packaging uses Hatch with hatch-regex-commit for version management from git tags, and uv as the dev-environment installer.

Code Quality The test suite spans 18 files under tests/, covering each router, the authenticator, each authentication strategy (JWT, DB, Redis), transports, the JWT helpers, and the manager, with pytest-asyncio for async test support. CI enforces --cov-fail-under=100, meaning every merged change must maintain full statement coverage — a notably strict bar. The hatch run lint-check pipeline runs isort, ruff format, ruff check, and mypy across the source tree, and GitHub Actions runs the full lint+typecheck+test matrix across Python 3.10 through 3.14 on every push and pull request. Naming and typing are consistent throughout, with Generic[models.UP, models.ID] used pervasively for user-ID type flexibility (UUID, int, or custom types).

API Design The public surface favors composition over configuration files: a FastAPIUsers instance is built once from a get_user_manager dependency and a list of AuthenticationBackend instances, and each router (get_auth_router, get_register_router, get_users_router, get_verify_router, get_oauth_router) is requested individually and mounted with app.include_router(), which keeps unused flows (like email verification) opt-in rather than forced on every project. Every public method carries a docstring describing its parameters, and the extensive docs/ (mkdocs-based, with dedicated cookbook and migration sections) plus four runnable example apps (SQLAlchemy and Beanie, each with and without OAuth) substantially lower the time to a working integration, though the multi-generic type signatures (FastAPIUsers[models.UP, models.ID]) do require understanding Python generics to extend correctly.