DEV Community

Cover image for FastForge: A Modern FastAPI Boilerplate for Authentication-Driven Applications
Javad Zarezadeh
Javad Zarezadeh

Posted on

FastForge: A Modern FastAPI Boilerplate for Authentication-Driven Applications

#fastapi #authentication #webdev #python

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

Feature Description
Phone/Email OTP Auth Secure, flexible registration/login
JWT + Refresh Tokens Bulletproof session management
Role-Based Access Control (RBAC) Multiple, flexible user roles
Email Verification & Mock Service Out of the box
OTP Attempt Limiting Keeps brute-force attackers at bay
UUIDs for All IDs Scalable and reliable in distributed systems
Soft Delete & Identifier Hashing Privacy and data safety built-in
Health Checks / Pre-commit Hooks Quality you can trust
Docker & Local Setup Start up YOUR way

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)

Top comments (0)