DEV Community: Javad Zarezadeh

FastForge: A Modern FastAPI Boilerplate for Authentication-Driven Applications

Javad Zarezadeh — Sat, 18 Oct 2025 13:41:24 +0000

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:

KISS Principle – Minimal dependencies and clear.
Security First – Protection built-in from the start.
Best Practices – No hacky shortcuts.
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

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:

Star the repo on GitHub
Test it in your next project
Share your results with fellow devs
Help improve by contributing
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)

Mobile-First Approach for FastAPI Full-Stack Template Authentication: Migrating to phone_number/OTP

Javad Zarezadeh — Sun, 16 Feb 2025 14:20:31 +0000

As you may know, FastAPI is one of the most admired frameworks for developing RESTful APIs. Another fantastic project by the same author, @tiangolo, is the Full Stack FastAPI Template, which I previously wrote about here.

In this post, I'll guide you through the process of replacing the email/password authentication flow in the template with a phone_number/OTP-based system. This approach is ideal for mobile-first applications and offers a user-friendly, secure way to authenticate users. My goal is to make minimal changes to the original project while maintaining its adherence to OAuth2 and JWT standards. Let’s dive in! 😉

1. Replace `email` and `password` with `phone_number` and `otp`

Update Configuration

File: ./.env
Change Needed:

Update the FIRST_SUPERUSER value to a phone number, e.g., +17375550100 or +989130000000.
Remove FIRST_SUPERUSER_PASSWORD as it is no longer necessary.

Update the Models

File: ./backend/app/models.py
Changes Needed:

Replace all instances of the email field with phone_number.

Example:

email: EmailStr = Field(unique=True, index=True, max_length=255)

Change to:

phone_number: str = Field(unique=True, index=True, max_length=20)

⚠️ Important: This change requires updating the database schema using Alembic migrations.

Update API Routes

Private Routes

File: ./backend/app/api/routes/private.py
Replace all occurrences of email and password with phone_number and otp.

Login Route

File: ./backend/app/api/routes/login.py

Update the authenticate call:

user = crud.authenticate(session=session, email=form_data.username, password=form_data.password)

Change to:

user = crud.authenticate(session=session, phone_number=form_data.username, otp=form_data.password)

⚠️ Note: Keep form_data.username and form_data.password unchanged due to OAuth2 standards.

Update User CRUD

File: ./backend/app/api/routes/users.py

Replace email with phone_number.
Remove the if statement in the create_user function related to email validation.

Database Utilities

File: ./backend/app/core/db.py

Replace email references with phone_number.
Remove FIRST_SUPERUSER_PASSWORD as it is no longer necessary.

CRUD Operations

File: ./backend/app/crud.py

Replace all email and password references with phone_number and otp.
Rename get_user_by_email to get_user_by_phone_number and update all references to this function.

2. Add an API Endpoint to Request OTP

File: ./backend/app/api/routes/login.py

Add the following endpoint:

OTP_EXPIRE_MINUTES = 5

@router.post("/login/request-otp")
def request_otp(session: SessionDep, phone_number: str) -> Message:
    """
    Generate and send OTP to the provided phone number.
    """
    user = crud.get_user_by_phone_number(session=session, phone_number=phone_number)
    if not user:
        user = crud.create_user(session=session, user_create=UserCreate(phone_number=phone_number))

    otp = generate_otp()
    otp_expires_at = datetime.now(timezone.utc) + timedelta(minutes=OTP_EXPIRE_MINUTES)

    crud.update_user(
        session=session,
        db_user=user,
        user_in=UserUpdate(otp=otp, otp_expires_at=otp_expires_at),
    )

    send_otp(phone_number, otp)

    return Message(message="OTP sent successfully.")

3. Nullify OTP After Login

File: ./backend/app/api/routes/login.py
In the login_access_token function, nullify the OTP after successful login:

crud.update_user(
    session=session,
    db_user=user,
    user_in=UserUpdate(otp=None, otp_expires_at=None)
)

4. Remove Unnecessary Functions

File: ./backend/app/api/routes/login.py

Remove the following functions:

recover_password
reset_password
recover_password_html_content

5. Remove Unnecessary Email Features

File: ./backend/app/api/routes/users.py

Remove the email-related logic, such as:

if settings.emails_enabled and user_in.email: ...

6. Remove Password Update and User Registration Functions

File: ./backend/app/api/routes/users.py

Remove the following functions:

update_password_me
register_user

Since we are now using OTP-based authentication, these functions are redundant.

7. Simplify Models

File: ./backend/app/models.py

Replace `password` with `otp`:

Update all password fields to otp.

Example:

password: str | None = Field(default=None, min_length=8, max_length=40)

Change to:

otp: str | None = Field(default=None, max_length=6)

Remove OTP from `UserCreate`:

For the UserCreate model, you don’t need to include the otp field. Update it as follows:

class UserCreate(UserBase):
    pass

This simplifies the creation process since OTP will be generated later during login.

Add OTP Expiry Fields:

Add an otp_expires_at field to both the UserUpdate and User models.

Example:

otp_expires_at: datetime | None = Field(default=None, nullable=True)

Remove Unnecessary Models:

Delete models that are no longer needed, including:

UserRegister
UpdatePassword
NewPassword

This cleanup ensures the models remain relevant to the new authentication system.

8. Update Utilities

File: ./backend/app/utils.py

Remove unused functions:

generate_reset_password_email
generate_new_account_email
generate_password_reset_token
verify_password_reset_token

Add OTP Generation:

def generate_otp():
    return str(random.randint(100000, 999999))  # 6-digit OTP

Add SMS Sending:

def send_otp(phone_number: str, otp: str):
    """
    Sends an OTP to the provided phone number.
    """
    # Implement this function according to your SMS provider

    pass

Following these steps will transform the Full Stack FastAPI Template’s email/password flow into a phone_number/OTP-based system while keeping it aligned with best practices and standards. Happy coding! 🚀

These changes to the original project are available in my GitHub. It is important to use this project cautiously, since I have not yet had time to write the tests.

Why FastAPI Full-Stack Template Is My Go-To for Modern Web Development

Javad Zarezadeh — Sun, 26 Jan 2025 15:09:33 +0000

Python might not be the most modern programming language, but it’s undoubtedly one of the most widely used today. There’s an old Persian saying: "A thornless flower is divine." (گل بی‌خار خداست), which reminds us that nothing in the universe is without imperfections. Programming languages are no exception. Despite its performance issues (In comparison with compiled programming languages) and the infamous GIL, Python’s simplicity, vast community, and extensive library support far outweigh its shortcomings. Recent advancements in Python’s core are also paving the way for modern features like type hinting and concurrency—capabilities that were missing from the start.

With the introduction of type hinting in Python 3.5 and its gradual adoption as a default in Python 3.10, FastAPI emerged. The now-famous de facto framework for RESTful API development hardly needs an introduction. But here’s where I want to take a creative detour: "How I Learned to Stop Worrying and Love the Bomb."

Yes, you read that right. FastAPI is the “bomb” that’s shaking up Django and even other web development frameworks from different languages. It builds on Python’s strengths without reinventing the wheel. FastAPI embraces Python’s core language features, making the learning process feel like rediscovering Python itself—but in a better way. Trust me on this: the learning curve feels more like a joyride. Hell yeah, learning curve! 😜

While the many merits of FastAPI could fill pages, this article focuses on why I love using the full-stack template introduced by its author, @tiangolo (Sebastián Ramírez). Sebastián isn’t just a great open-source contributor—he’s an idol. His dedication goes beyond building his own tools; he also highlights other projects worth exploring and using for a lifetime.

Why I Love the Full-Stack Template

1. Gathering Modern Technologies

The template brings together a dream stack:

FastAPI for the backend
PostgreSQL for the database
React for the frontend
Docker Compose for DevOps

You can find the full list of technologies here.

2. Rocket-Fast Performance!

Despite being based on Python, FastAPI’s performance is undoubtedly impressive. This is thanks to its foundation on two powerful tools: Starlette and Uvicorn. If you’ve worked with Django, you might know its performance isn’t its strongest suit. But take a look at the TechEmpower Benchmark: FastAPI’s performance outshines Flask and is miles ahead of Django—not just far, but far, far, far better!

3. The Dirty Work is Already Done!

You might think, "So what? I know these technologies and can integrate them myself." Fair point, but let’s be real—configuring and bridging these tools can be a nightmare. This template handles that for you, using best practices throughout. Why not trust it? By narrowing down the stack, you free your mind from debating JS/TS, Vite/Webpack, Chakra UI/Material UI, and so on. Straight to the code!

4. Learning from Top Developers

Before using this template, I hadn’t even heard of technologies like Traefik, Playwright, or Chakra UI. Discovering these tools through the template introduced me to industry best practices and inspired me to learn more.

5. Well-Organized Code and Best Practices

I won’t dive too deep into the codebase, but one highlight is its exceptional implementation of user authentication. It uses OAuth2 and JWT standards—and nails it. Although the structure might feel complex at first glance, you’ll soon appreciate why it’s designed this way.

6. Customization Right Out of the Box

Do you prefer to stick with the backend and implement the frontend using your favorite framework, like Svelte? Not a problem! Removing the frontend folder is almost all you need to do. The template supports easy customization, whether on the backend or frontend, allowing you to tailor it to your specific needs.

7. Documentation and Community Support

Both FastAPI and the full-stack template have robust documentation. Additionally, there’s an active community around FastAPI, so finding solutions to issues or learning best practices is relatively easy.

The Downsides

1. Pull Request Review Delays

Sebastián maintains many amazing projects, so PR reviews can take longer than expected. On the bright side, he’s welcoming and offers warm responses when he has time to engage.

2. Complexity for Beginners

While the template is powerful, its structure and integrations can feel overwhelming to beginners. New developers might need extra time to understand how all the pieces fit together.

3. Maintenance of Customized Projects

Once you’ve customized the template, keeping your project up-to-date with upstream changes can be tricky. Merging updates from the original repository requires careful attention to avoid conflicts with your customizations.

In conclusion, the full-stack FastAPI template isn’t just a collection of tools; it’s a thoughtfully crafted framework that balances modern technologies with ease of use. It’s not perfect—just like Python or anything else in life—but as the saying goes, "A thornless flower is divine."

DEV Community: Javad Zarezadeh

FastForge: A Modern FastAPI Boilerplate for Authentication-Driven Applications

Why FastForge?

Core Principles

Features at a Glance

Authentication & Authorization

Role-Based Access Control (RBAC)

Tech Stack & Quality

Project Structure

Getting Started

Prerequisites

Quick Start With Docker

Local Development

API Docs

Contributing & Community

Call To Action

Support the Project

Mobile-First Approach for FastAPI Full-Stack Template Authentication: Migrating to phone_number/OTP

1. Replace email and password with phone_number and otp

Update Configuration

Update the Models

Update API Routes

Private Routes

Login Route

Update User CRUD

Database Utilities

CRUD Operations

2. Add an API Endpoint to Request OTP

3. Nullify OTP After Login

4. Remove Unnecessary Functions

5. Remove Unnecessary Email Features

6. Remove Password Update and User Registration Functions

7. Simplify Models

Replace password with otp:

Remove OTP from UserCreate:

Add OTP Expiry Fields:

Remove Unnecessary Models:

8. Update Utilities

Add OTP Generation:

Add SMS Sending:

Why FastAPI Full-Stack Template Is My Go-To for Modern Web Development

Why I Love the Full-Stack Template

1. Gathering Modern Technologies

2. Rocket-Fast Performance!

3. The Dirty Work is Already Done!

4. Learning from Top Developers

5. Well-Organized Code and Best Practices

6. Customization Right Out of the Box

7. Documentation and Community Support

The Downsides

1. Pull Request Review Delays

2. Complexity for Beginners

3. Maintenance of Customized Projects

1. Replace `email` and `password` with `phone_number` and `otp`

Replace `password` with `otp`:

Remove OTP from `UserCreate`: