FastForge: A Modern FastAPI Boilerplate for Authentication-Driven Applications

Are you tired of losing time setting up authentication for your FastAPI projects? FastForge is a lightweight, secure, and scalable FastAPI boilerplate built for rapid development of authentication-driven apps. It features robust authentication with phone-based OTP verification and role-based access control, using modern Python tools and best practices.

👉 View FastForge on GitHub

Why FastForge?

Let’s be real: setting up authentication is a pain. I’ve lost days tweaking templates that didn’t quite fit my needs: too complex, too rigid, or just not my style. The official Full-stack FastAPI Template is awesome, but I wanted something leaner, faster, and built for phone-based OTP flows without leaning on third-party OAuth2 servers. So, I rolled up my sleeves and created FastForge.

Core Principles

FastForge is built on a few non-negotiables:

1. 
   KISS Principle – Minimal dependencies and clear.


2. 
   Security First – Protection built-in from the start.


3. 
   Best Practices – No hacky shortcuts.


4. 
   Scalability – Ready to grow when your app takes off.

Features at a Glance

Authentication & Authorization

Authentication is usually the thing developers dread, and end up procrastinating for days (been there so many times 😁). FastForge gives you a modern phone number/OTP setup. No more old-school username/password headaches or dependency on third-party OAuth. In FastForge, your phone (or email) is your username, and OTP is your password. All built on OAuth2 standards, so you get compatibility with Swagger UI for easy testing.

Here’s what you get out of the box:

• OTP attempt limiting (a real brute-force stopper)


• Email verification


• JWT management with refresh token rotation


• Login with phone or email, form data and JSON payloads

Works great for web and mobile.

Role-Based Access Control (RBAC)

Access control shouldn’t slow you down or lock you into spaghetti code. FastForge uses JWT to encode roles (so no extra DB checks!), supports many-to-many user-role relationships, and adapts to all kinds of systems: imagine a football club app with roles for Manager, Player, Staff, and Fan. Users can have multiple roles at once, just like a player-manager who’s also a fan (think Kenny Dalglish). Roles are assigned via the UserRoleLink table, right in the core.

Tech Stack & Quality

These are the tools that power FastForge:

• 
  FastAPI (by @tiangolo) – High-performance web framework, with flawless API docs


• 
  SQLModel – Combines SQLAlchemy and Pydantic for type-safe DB ops


• 
  PostgreSQL & Redis – Solid backends, quick OTP storage (TTL configured)


• 
  PyJWT – Secure token management


• 
  SlowAPI – Rate limiting, fast and simple


• 
  uv – Lightning-fast Python dependency installer


• 
  Pydantic – Input and data validation made easy


• 
  Alembic – DB migrations are no longer scary


• 
  Ruff and isort – Code quality and style


• 
  pytest/pytest-asyncio/pytest-cov – Testing and coverage

Project Structure

Here’s how everything fits together (so you won’t get lost):

fastforge/

├── src/

│   ├── main.py               # App entry point

│   ├── auth.py               # Auth logic

│   ├── routes/               # REST endpoints

│   ├── models/               # ORM models

│   └── config.py             # Centralized config

├── migrations/               # Alembic migrations

├── tests/                    # Test suite

├── .env.example              # Example config

├── Dockerfile/docker-compose.yml

For an extended dive, check the README!

Getting Started

Ready to code? FastForge works both locally and with Docker.

Prerequisites

• 
  Python: 3.13 or higher


• 
  Docker: Latest, with Compose


• 
  PostgreSQL & Redis (provided via Docker, or install locally)

Quick Start With Docker

git clone https://github.com/javadzarezadeh/fastforge.git

cd fastforge

docker compose up --build

API lives at http://localhost:8000, docs at /docs and /redoc, and Adminer at http://localhost:8081 (handy for DB peeking).

Local Development

git clone https://github.com/javadzarezadeh/fastforge.git

cd fastforge

uv sync

cp .env.example .env

uv run alembic upgrade head

uv run fastapi run src/main.py --port 8000 --host 0.0.0.0

Check your terminal for OTP logs (when using mock SMS), and for Docker, get them via docker compose logs app.

API Docs

Hit the full interactive docs at

• 
  http://localhost:8000/docs (Swagger UI)


• 
  http://localhost:8000/redoc (ReDoc)

Contributing & Community

Open-source is better when we build it together! Bugs, features, docs, or feedback. Just fork, branch, code, and PR. Pre-commit hooks and tests keep things tight.

I always appreciate hearing from you:

• Authentication flow usability


• Documentation clarity


• Real-world performance


• Cool features on your wish list


• Feedback for making FastForge even easier for developers

Call To Action

Ready to save time and boost security? Try FastForge now:

1. 
   Star the repo on GitHub


2. Test it in your next project


3. Share your results with fellow devs


4. Help improve by contributing


5. Support development with a donation

Together, we can make FastAPI authentication painless and powerful!

Find FastForge on GitHub: https://github.com/javadzarezadeh/fastforge

Support the Project

If FastForge speeds up your workflow, please consider donating. Your support keeps the project growing and improving.

Crypto donations:

• 
  Bitcoin: bc1qnk9dvr2zpp42rdrf4td99d3r5g4ylg0wlngpy0
  


• 
  Ethereum: 0x9D0C185Ed0BbfeFc9dC392D2E3d72Be2635D3BA3
  


• 
  TON: UQA6dCXas-TAbpiH7ATdgSxKze1iekkxFz1ch-Z79GwDnFGw
  


• 
  USDT/USDC/DAI (ERC20): 0x9D0C185Ed0BbfeFc9dC392D2E3d72Be2635D3BA3
  

Let FastForge do the heavy lifting for authentication, and get you building faster! Enjoy coding.

(https://github.com/javadzarezadeh/fastforge)