crudauth 0.2.1

Batteries-included, transport-agnostic authentication for FastAPI.

Batteries-included, transport-agnostic authentication for FastAPI.

Docs · DeepWiki · Discord

---

crudauth gives you one CRUDAuth object that wires cookie sessions, JWT bearer tokens, OAuth, and email flows (verify / reset / change) - with CSRF, escalating login lockout, sudo mode, and multi-device session management - over your own SQLAlchemy User model. App policy lives in hooks, not in forked dependency code. Sessions and bearer both resolve to the same Principal, so narrowing or adding a transport never changes how you authorize a route.

---

Features

• Transport-agnostic: cookie sessions and JWT bearer tokens behind a single Principal; first credential present wins, and authorization code never depends on which transport authenticated.
• Your model, your schema: works over your existing SQLAlchemy User via a logical-field column_map - no forced renames, no second user table.
• Secure by default: synchronizer-token CSRF, escalating per-IP/per-user login lockout, bcrypt with SHA-256 pre-hash (no 72-byte truncation), timing-equalized login, and trusted-proxy IP resolution.
• OAuth: Google, GitHub, or a custom provider - with the state bound to the initiating browser to block login CSRF.
• Email flows: verify / reset / change - you implement the EmailSender port, the package mints and verifies the signed, single-use tokens.
• Sudo mode: short-lived re-authentication to gate sensitive actions, stamped on the session and cleared on logout.
• Multi-device sessions: list, revoke one, or "sign out everywhere", with a configurable per-user session cap.
• App policy in hooks: AuthHooks for welcome email, trial grant, audit logging - fired uniformly across every auth path.
• Pluggable backends: in-memory for dev, Redis for production - for sessions, CSRF, lockout counters, and one-time tokens.
• Fully typed & async: ships py.typed, built on SQLAlchemy 2.0 and Pydantic v2.

Requirements

• Python 3.10+
• FastAPI, SQLAlchemy 2.0+, Pydantic v2 (installed as dependencies)

Install

pip install crudauth            # core (session + bearer)
pip install "crudauth[all]"     # + httpx (oauth), redis, user-agents

Or with uv:

uv add crudauth

Quickstart

Sessions are the default - no transports= needed. You get cookie auth, CSRF, login lockout, secure cookies, and /login /logout /register /me.

from fastapi import FastAPI, Depends
from crudauth import CRUDAuth, Principal
from myapp.db import get_session
from myapp.models import User

auth = CRUDAuth(session=get_session, user_model=User, SECRET_KEY="change-me")

app = FastAPI()
app.include_router(auth.router)

@app.get("/dashboard")
async def dashboard(me: Principal = Depends(auth.current_user())):
    return {"hello": me.user.username}

The user model

Inherit the mixin and get every column the package needs; your own columns coexist freely.

from sqlalchemy.orm import Mapped, mapped_column
from crudauth.models import AuthUserMixin
from myapp.db import Base

class User(Base, AuthUserMixin):
    __tablename__ = "users"
    full_name: Mapped[str | None] = mapped_column(default=None)

Existing table with different names? Map the contract, don't rename your schema:

auth = CRUDAuth(
    session=get_session, user_model=LegacyAccount, SECRET_KEY=...,
    column_map={"id": "account_id", "email": "email_address", "hashed_password": "pw_hash"},
)

Protecting routes - one factory, every case a kwarg

auth.current_user()                              # required, 401 if anon
auth.current_user(optional=True)                 # None instead of raising
auth.current_user(superuser=True)                # 403 unless is_superuser
auth.current_user(verified=True)                 # 403 unless email_verified
auth.current_user(scopes=["reports:read"])       # 403 unless scopes ⊇ required
auth.current_user(transport="bearer")            # narrow to one transport
auth.current_user(superuser=True, check=my_predicate)  # extra per-route check

The resolved Principal carries user_id, is_superuser, scopes, transport (which transport authed the request), and user (your resolved row).

Multiple transports, one identity

from crudauth import CRUDAuth, SessionTransport, BearerTransport

auth = CRUDAuth(
    session=get_session, user_model=User, SECRET_KEY=...,
    transports=[
        SessionTransport(backend="redis", redis_url=..., csrf=True),  # browsers
        BearerTransport(access_ttl=900, refresh="cookie"),            # apps/scripts
    ],
)

When both credentials are present, the first transport in the list wins. CSRF is a property of the session transport - it appears only where sessions do, never on bearer/api-key paths.

Storage & lifespan

Server-side backends open connections on startup - call initialize() / shutdown() in your lifespan:

@asynccontextmanager
async def lifespan(app: FastAPI):
    await auth.initialize()
    yield
    await auth.shutdown()

OAuth, email, hooks, sudo

See the usage cookbook for OAuth (Google / GitHub / custom providers), email flows (implement the EmailSender port; the package mints/verifies the signed tokens), lifecycle hooks (AuthHooks - welcome email, trial grant, audit log), sudo mode (sudo=SudoConfig() + auth.require_sudo()), and dropping to primitives.

Architecture

crudauth is ports-and-adapters with feature slices and a single composition root (CRUDAuth). The layering and the import-direction rules live in crudauth/ARCHITECTURE.md - read it before adding a transport, OAuth provider, or storage backend; each is meant to be a drop-in file, not a cross-cutting edit.

License

MIT

Contact

Benav Labs – benav.io, Discord

The Benav Labs FastAPI family

crudauth is part of a family of composable FastAPI building blocks - use whichever you need:

• FastCRUD - powerful CRUD methods and automatic endpoint creation for your SQLAlchemy models.
• CRUDAdmin - a modern, secure admin interface generated straight from your models.
• Fastro (FastAPI-boilerplate) - a batteries-included FastAPI starter: auth, CRUD, jobs, caching, and rate-limits.
• FastroAI - the complete FastAPI SaaS template: payments, entitlements, email, a frontend, and AI agents.

Build a full SaaS on FastAPI

crudauth handles authentication in FastroAI - the complete FastAPI SaaS template: auth, Stripe payments (subscriptions, credits, discounts), entitlements, transactional email, an Astro frontend, and PydanticAI agents, wired together and production-ready.

Ship your SaaS faster with FastroAI →

---