Skip to content
Authentication for FastAPI

Login, tokens,
and roles.
Wired in one call.

FastAuth adds JWT access and refresh tokens, role-based access control, and ready-made login routes to any FastAPI + SQLModel app. Call auth.setup(app) and start protecting routes.

Get startedGitHub
uv add fastauth_iq "fastapi[standard]"

v0.7.0 · MIT · tested on Python 3.10–3.14

Features

Everything auth, nothing extra

FastAuth covers the auth work every FastAPI app repeats: token issuing, password hashing, session cookies, and role checks. Your code stays about your product.

One call mounts everything

Login, refresh, registration, logout, password reset, email verification, and the role API, all wired at once.

main.py
auth = FastAuth(engine=engine)
auth.setup(app)

19 routes across auth, account flows, and role management, plus the error handlers.

Two tokens, two lifetimes

A short-lived access token for API calls, a long-lived refresh token so users are not asked to log in every half hour.

access_token30 min
refresh_token7 days

/token/refresh mints a new access token without asking for the password again.

Roles that read like English

Six standard roles out of the box. Protect a single route or a whole router.

auth.roles(...)
any of these roles
auth.all_roles(...)
all of these roles
auth.admin
the admin shortcut

Cookies with the right flags

An HTTP-only cookie that expires with its token. A Bearer header wins when both are present.

HttpOnly
JavaScript can never read it
Secure
HTTPS only, default in production
SameSite=lax
blocks cross-site sends

Errors in one shape

Every auth failure returns the same JSON with a machine-readable code, so clients handle errors once.

code
FASTAUTH_INVALID_CREDENTIALS
message
Incorrect username or password
status_code
401

Account flows

Password reset, change, and email verification, with delivery hooks for your email service.

Production mode

production=True enforces a strong secret, secure cookies, and no default passwords.

CLI initialization

fastauth app.py creates tables, the six standard roles, and a superadmin.

SQLModel native

Bring your own engine and user model. No separate auth database, no second source of truth.

bcrypt hashing

Hashes with bcrypt directly, compatible with bcrypt 4 and 5, with no passlib dependency to keep pinned.

Token revocation

/logout/all invalidates every session, and password changes do it automatically.

Quick start

A working auth system in three steps

Login, refresh tokens, registration, roles, and protected routes. Run uv run fastapi dev main.py and every endpoint is in /docs, documented and ready to try.

1

Install the package

One dependency, plus FastAPI's standard extras for the dev server.

shell
uv add fastauth_iq "fastapi[standard]"
2

Wire FastAuth into your app

Point it at your engine and session. One call mounts every route and the error handlers.

main.py
from fastapi import FastAPI
from sqlmodel import create_engine
from fastauth import FastAuth

engine = create_engine("sqlite:///./app.db")
auth = FastAuth(secret_key="...", engine=engine, use_cookie=True)

app = FastAPI()
auth.setup(app, session_getter=get_session)
3

Protect your routes

Depend on the current user, a set of roles, or the admin shortcut.

main.py
@app.get("/protected")
def protected(user: User = Depends(auth.current_user)):
    return {"message": f"Hello, {user.username}!"}

@app.get("/admin-only")
def admin(user: User = Depends(auth.admin)):
    return {"message": "Admins only"}
Read the quick startNew to FastAPI? Try easy mode

Stop rewriting auth

Install it, call auth.setup(app), and get back to the part of your app that is actually yours.

uv add fastauth_iq "fastapi[standard]"Read the docs