RBAC Auth
A FastAPI authentication and authorization template for multi tenant apps: declarative role guards, rotating refresh tokens with reuse detection, Redis sessions and async SQLAlchemy migrations.
Overview
RBAC Auth is a starting point you fork and tailor: keep the auth and role
skeleton, swap the domain models. Authorization is declared on the route with
@Roles(...) and enforced by RolesGuard, so adding a
protected endpoint never means editing the guard itself.
POST /auth/login -> access + refresh pair
POST /auth/refresh -> rotate the pair (reuse revokes every session)
GET /admin/... -> @Roles(ADMIN) + RolesGuard
Redis -> session set, TTL eviction, access revocation
PostgreSQL -> users, roles, refresh tokens, email log
Key features
- Declarative roles
@Roles(Role.ADMIN)plusRolesGuard; no inline permission checks in controllers. - Refresh rotationOne time refresh tokens with reuse detection; reuse invalidates every session for that user.
- Redis sessionsNative TTL eviction, access token revocation, logout and logout all.
- Roles as dataA
rolestable and a many to manyuser_roles, seeded with ADMIN and USER. - Email verificationHashed verification tokens and an
EmailLogstate machine. - Migrations + CIAlembic autogenerate, ruff + pre-commit, and pytest with an 80% coverage gate.
How it works
- Sync dependencies with
uvand copy.env.exampleto.env. - Run
alembic upgrade headagainst PostgreSQL. - Bootstrap the first admin (environment mode, or the hidden HTTP route).
- Start the app and sign in; the Scalar docs live at
/docs.
uv sync --all-groups
alembic upgrade head
uv run uvicorn app.main:app --reload
# endpoints are mounted under /api/v1
Stack
FastAPI
SQLAlchemy 2 async
PostgreSQL
Redis
Alembic
bcrypt
PyJWT
Scalar
uv
pytest