Modern web applications need a reliable way to verify who users are and control what they are allowed to access. FastAPI authentication with JWT is a popular approach for building secure authentication systems for APIs, mobile applications, and modern frontend applications.
In this guide, you’ll learn how to build JWT authentication in FastAPI from the ground up. We’ll cover user registration, password hashing, login, access tokens, protected routes, token validation, refresh tokens, common security mistakes, and production best practices.
The examples are designed to be beginner-friendly while following patterns that can be extended for real-world applications.
What Is Authentication?
Authentication is the process of verifying a user’s identity.
For example, when a user logs into an application with an email and password, the server verifies those credentials before allowing access to protected resources.
A typical authentication flow looks like this:
User
│
│ Email + Password
▼
FastAPI Login Endpoint
│
│ Verify credentials
▼
Password Hash
│
│ Valid?
├────────────── No ──────► 401 Unauthorized
│
▼ Yes
Generate JWT
│
▼
Return Access Token
│
▼
Client stores token
│
│ Authorization: Bearer <token>
▼
Protected FastAPI Endpoint
│
▼
Validate JWT
│
▼
Return Protected Data
The key idea is that the server does not need to ask the user for their password on every request.
What Is JWT?
JWT stands for JSON Web Token.
A JWT is a compact token commonly used to securely transmit claims between a client and server.
A JWT typically contains three parts:
HEADER.PAYLOAD.SIGNATURE
For example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJzdWIiOiIxMjMiLCJleHAiOjE3NjYwMDAwMDB9
.
signature
The three components are:
| Component | Purpose |
|---|---|
| Header | Contains token metadata such as the signing algorithm |
| Payload | Contains claims such as user ID and expiration |
| Signature | Helps verify that the token has not been modified |
JWTs are signed, not encrypted by default. Therefore, you should not put passwords, secrets, or other sensitive information inside the JWT payload.
Why Use JWT Authentication With FastAPI?
FastAPI is well suited to API-based authentication because it provides dependency injection, request validation, and security utilities that make authentication flows easier to structure.
JWT authentication can be useful when:
- Building REST APIs
- Creating mobile backends
- Building SPA backends
- Creating microservices
- Supporting stateless authentication
- Implementing role-based authorization
- Protecting private API endpoints
A common architecture is:
Frontend / Mobile App
│
│ Login
▼
FastAPI
│
├── Verify password
│
└── Generate JWT
│
▼
Access Token
│
▼
Frontend sends token with requests
│
▼
Protected API
JWT Authentication vs Session Authentication
JWT authentication is not the only authentication approach.
Traditional session-based authentication stores session state on the server, while JWT-based authentication typically allows the server to validate a signed token without maintaining the same kind of session record.
| Feature | JWT Authentication | Session Authentication |
|---|---|---|
| Token/state | Token carries claims | Server maintains session |
| Server-side session | Usually not required | Usually required |
| API friendly | Yes | Yes |
| Stateless design | Common | Less common |
| Token revocation | Requires additional design | Usually straightforward |
| Scaling | Convenient for stateless APIs | Often requires shared session storage |
JWT is useful, but it isn’t automatically more secure than sessions. Security depends heavily on how tokens are created, stored, transmitted, expired, and revoked.
Project Setup
Let’s create a simple FastAPI authentication project.
A possible project structure is:
fastapi-auth/
│
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── auth.py
│ ├── models.py
│ └── database.py
│
├── requirements.txt
└── .env
For a production application, you may separate routers, schemas, services, database models, configuration, and security utilities into dedicated modules.
Installing FastAPI and Authentication Dependencies
Create a virtual environment:
python -m venv venv
Activate it on Windows:
venv\Scripts\activate
On macOS or Linux:
source venv/bin/activate
Install the required packages:
pip install fastapi uvicorn pyjwt pwdlib
For form-based OAuth2 login support, you can also install:
pip install python-multipart
The exact dependency versions should be pinned and regularly updated in a production project.
Creating the FastAPI Application
Start with a simple application:
from fastapi import FastAPI
app = FastAPI(title="FastAPI JWT Authentication")
@app.get("/")
def home():
return {"message": "API is running"}
Run it with Uvicorn:
uvicorn app.main:app --reload
You should then be able to access the FastAPI application locally.
FastAPI also provides interactive API documentation, which is especially useful when testing authentication endpoints.
Creating a User Model
For this tutorial, we’ll use a simple Python dictionary to demonstrate the authentication logic.
In a real application, user information should normally be stored in a database.
fake_users_db = {
"aarav@example.com": {
"username": "aarav@example.com",
"full_name": "Aarav Sharma",
"hashed_password": "...",
"disabled": False
}
}
A real application could use:
- PostgreSQL
- MySQL
- MongoDB
- SQLite
- Another supported database
The authentication architecture remains similar regardless of the database.
Never Store Plain-Text Passwords
One of the most important authentication rules is:
Never store user passwords as plain text.
Do not store:
password123
Instead, store a secure password hash.
For example:
password123
│
▼
Password Hashing Algorithm
│
▼
$hashed_password_value
During login:
Submitted Password
│
▼
Verify Against Stored Hash
│
┌───┴───┐
│ │
Valid Invalid
│ │
▼ ▼
Login Reject
Hashing Passwords With pwdlib
Modern FastAPI examples can use pwdlib for password hashing.
from pwdlib import PasswordHash
password_hash = PasswordHash.recommended()
Create a password hash:
hashed_password = password_hash.hash("my-secret-password")
print(hashed_password)
The resulting hash should be stored instead of the original password.
Verifying a Password
When the user logs in, compare the submitted password with the stored hash.
is_valid = password_hash.verify(
"my-secret-password",
hashed_password
)
print(is_valid)
If the password is correct, the result is True.
Otherwise, it is False.
Creating JWT Tokens
Now we need a way to generate JWT access tokens.
We’ll use the PyJWT package.
import jwt
Define a strong secret key:
SECRET_KEY = "change-this-in-production"
ALGORITHM = "HS256"
For production, the secret should come from secure configuration rather than being hard-coded.
For example:
.env
could contain:
JWT_SECRET_KEY=your-long-random-secret
Do not commit real secrets to Git repositories.
Generating an Access Token
Create a helper function:
from datetime import datetime, timedelta, timezone
import jwt
SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
def create_access_token(data: dict, expires_delta: timedelta):
payload = data.copy()
expire = datetime.now(timezone.utc) + expires_delta
payload.update({"exp": expire})
return jwt.encode(
payload,
SECRET_KEY,
algorithm=ALGORITHM
)
Now you can generate a token:
token = create_access_token(
{"sub": "aarav@example.com"},
timedelta(minutes=30)
)
print(token)
The sub claim identifies the subject of the token.
Why Should JWTs Expire?
Access tokens should generally have a limited lifetime.
For example:
Login
│
▼
Access Token
│
├── 10 minutes
├── 20 minutes
└── 30 minutes
│
▼
Expired
Short-lived access tokens reduce the amount of time an attacker can potentially use a stolen token.
A common architecture is:
Short-lived Access Token
+
Longer-lived Refresh Token
We’ll discuss refresh tokens later.
Creating a Login Endpoint
FastAPI provides OAuth2 utilities that can simplify bearer-token authentication.
Import the necessary components:
from fastapi.security import OAuth2PasswordBearer
Create the bearer configuration:
oauth2_scheme = OAuth2PasswordBearer(
tokenUrl="token"
)
This tells FastAPI where clients can obtain a token.
Building the Login Endpoint
A simple authentication endpoint can look like this:
from fastapi import FastAPI, HTTPException
from fastapi.security import OAuth2PasswordRequestForm
app = FastAPI()
@app.post("/token")
async def login(
form_data: OAuth2PasswordRequestForm = Depends()
):
user = fake_users_db.get(form_data.username)
if not user:
raise HTTPException(
status_code=401,
detail="Incorrect username or password"
)
if not password_hash.verify(
form_data.password,
user["hashed_password"]
):
raise HTTPException(
status_code=401,
detail="Incorrect username or password"
)
access_token = create_access_token(
{"sub": user["username"]},
timedelta(minutes=30)
)
return {
"access_token": access_token,
"token_type": "bearer"
}
Remember to import Depends:
from fastapi import Depends
The response looks like:
{
"access_token": "eyJhbGciOi...",
"token_type": "bearer"
}
How the Login Flow Works
The complete process is:
LOGIN FLOW
Client
│
│ username + password
▼
POST /token
│
▼
Find User
│
▼
Verify Password Hash
│
├──────── Invalid ───────► 401
│
▼ Valid
Create JWT
│
▼
Return Access Token
│
▼
Client
The client can then use the access token for protected API requests.
Protecting a FastAPI Route
Now let’s create a protected endpoint.
@app.get("/users/me")
async def read_current_user(
token: str = Depends(oauth2_scheme)
):
return {
"message": "You are authenticated",
"token": token
}
The oauth2_scheme dependency extracts the bearer token from the request.
A client sends:
Authorization: Bearer <access_token>
However, simply extracting the token isn’t enough.
We need to decode and validate it.
Decoding and Validating the JWT
Create a function that validates the token:
from fastapi import HTTPException, status
def decode_access_token(token: str):
try:
payload = jwt.decode(
token,
SECRET_KEY,
algorithms=[ALGORITHM]
)
username = payload.get("sub")
if username is None:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication credentials"
)
return username
except jwt.InvalidTokenError:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication credentials"
)
This function:
- Decodes the JWT.
- Verifies the signature.
- Checks token claims.
- Retrieves the user identity.
- Rejects invalid tokens.
Creating a Current User Dependency
Instead of repeating authentication logic in every endpoint, FastAPI’s dependency injection system lets us centralize it.
async def get_current_user(
token: str = Depends(oauth2_scheme)
):
username = decode_access_token(token)
user = fake_users_db.get(username)
if user is None:
raise HTTPException(
status_code=401,
detail="User not found"
)
return user
Now protected endpoints become much cleaner.
@app.get("/users/me")
async def get_profile(
current_user: dict = Depends(get_current_user)
):
return current_user
This is one of the most useful patterns when implementing FastAPI JWT authentication.
Complete Authentication Flow
The resulting architecture looks like this:
┌──────────────┐
│ Client │
└──────┬───────┘
│
│ Email + Password
▼
┌──────────────┐
│ POST /token │
└──────┬───────┘
│
▼
┌────────────────────┐
│ Verify User + Hash │
└─────────┬──────────┘
│
▼
┌────────────┐
│ Create JWT │
└─────┬──────┘
│
▼
Access Token
│
│ Authorization:
│ Bearer <token>
▼
┌──────────────────────┐
│ Protected FastAPI │
│ Endpoint │
└──────────┬───────────┘
│
▼
Validate JWT
│
┌───┴───┐
│ │
Valid Invalid
│ │
▼ ▼
Continue 401
Adding User Registration
Authentication normally starts with registration.
A registration endpoint might accept:
{
"email": "aarav@example.com",
"password": "strong-password",
"full_name": "Aarav Sharma"
}
Define a Pydantic model:
from pydantic import BaseModel, EmailStr
class UserCreate(BaseModel):
email: EmailStr
password: str
full_name: str
Then create a registration endpoint:
@app.post("/register")
async def register(user: UserCreate):
if user.email in fake_users_db:
raise HTTPException(
status_code=400,
detail="User already exists"
)
hashed_password = password_hash.hash(
user.password
)
fake_users_db[user.email] = {
"username": user.email,
"full_name": user.full_name,
"hashed_password": hashed_password,
"disabled": False
}
return {
"message": "User registered successfully"
}
In a real application, replace the in-memory dictionary with a database.
Database Integration
For production authentication, users should be persisted in a database.
A typical user table or collection might contain:
| Field | Example |
|---|---|
id | 101 |
email | aarav@example.com |
password_hash | Hashed password |
full_name | Aarav Sharma |
is_active | true |
role | user |
created_at | Timestamp |
The database should never store the user’s plain-text password.
A production request flow becomes:
POST /login
│
▼
Validate Input
│
▼
Query Database
│
▼
Verify Password Hash
│
▼
Generate JWT
│
▼
Return Token
Adding User Roles
Authentication answers:
Who are you?
Authorization answers:
What are you allowed to do?
For example, users could have roles:
user = {
"id": 101,
"email": "admin@example.com",
"role": "admin"
}
The JWT could contain a role claim:
access_token = create_access_token(
{
"sub": user["email"],
"role": user["role"]
},
timedelta(minutes=30)
)
Then protected endpoints can verify permissions.
For example:
User
│
├── role = user
│ └── Read own profile
│
└── role = admin
├── Read users
├── Update users
└── Delete users
Keep authentication and authorization conceptually separate even though they often work together.
Access Tokens and Refresh Tokens
A common production architecture uses two types of tokens.
Access Token
Used to access protected resources.
Short lifetime
│
▼
API requests
Refresh Token
Used to obtain a new access token.
Longer lifetime
│
▼
Request new access token
The flow becomes:
Login
│
▼
┌────────────────┐
│ Access Token │
│ Short-lived │
└───────┬────────┘
│
▼
API Requests
│
▼
Expired
│
▼
Refresh Token
│
▼
New Access Token
Refresh-token implementations require additional security considerations, such as secure storage, rotation, expiration, and revocation.
Where Should JWTs Be Stored?
Token storage is an important security decision.
Common approaches include:
| Storage | Advantages | Risks |
|---|---|---|
| Memory | Reduced persistent exposure | Lost on refresh |
| Secure HttpOnly cookie | JavaScript cannot directly read it | Requires CSRF considerations |
| Local Storage | Easy to implement | XSS can expose tokens |
| Session Storage | Limited browser lifetime | XSS remains a concern |
There is no universal storage choice for every architecture.
For browser applications, carefully designed HttpOnly, Secure, SameSite cookies can be preferable to exposing long-lived tokens to JavaScript.
For mobile applications, use the platform’s secure credential storage mechanisms.
Important JWT Security Practices
Use a Strong Secret Key
Do not use:
SECRET_KEY = "123456"
Use a long, unpredictable secret generated specifically for your application.
Never Put Passwords in JWT Payloads
Never do this:
{
"username": "aarav",
"password": "secret123"
}
JWT payloads are not automatically encrypted.
Store only the minimum claims required by your application.
Set Token Expiration
Avoid tokens that never expire.
Use an expiration claim:
{
"sub": "aarav@example.com",
"exp": 1760000000
}
Short-lived access tokens can reduce risk if a token is compromised.
Always Use HTTPS
Authentication credentials and tokens should be transmitted over HTTPS.
Without HTTPS, attackers may be able to intercept sensitive traffic.
Validate the JWT Algorithm
When decoding JWTs, explicitly specify the algorithms your application accepts:
jwt.decode(
token,
SECRET_KEY,
algorithms=["HS256"]
)
Do not blindly trust an algorithm supplied by an untrusted token.
Don’t Put Sensitive Information in JWTs
Avoid storing:
- Passwords
- Credit card information
- API secrets
- Private personal information
- Database credentials
JWT payloads should contain only appropriate claims.
Common FastAPI JWT Authentication Mistakes
1. Storing Plain-Text Passwords
Bad:
user["password"] = "password123"
Good:
user["hashed_password"] = password_hash.hash(
"password123"
)
2. Hard-Coding Secrets
Avoid:
SECRET_KEY = "my-secret"
Use environment variables or a dedicated secret-management system.
3. Creating Tokens Without Expiration
An indefinitely valid access token increases the impact of token theft.
Always design a token lifetime.
4. Returning Too Much User Data
Avoid returning internal information such as:
{
"id": 101,
"email": "user@example.com",
"password_hash": "...",
"internal_notes": "..."
}
Create response schemas that expose only the data clients need.
5. Confusing Authentication With Authorization
Successfully logging in doesn’t mean a user should have access to every endpoint.
For example:
Authentication
│
▼
Is this user valid?
│
▼
Authorization
│
▼
Can this user perform this action?
Both layers are important.
Testing JWT Authentication
A good authentication system should test both successful and unsuccessful scenarios.
Important test cases include:
| Test | Expected Result |
|---|---|
| Valid registration | User created |
| Duplicate registration | Rejected |
| Correct password | Login succeeds |
| Wrong password | 401 Unauthorized |
| Missing token | 401 Unauthorized |
| Invalid token | 401 Unauthorized |
| Expired token | 401 Unauthorized |
| Deleted user | Access rejected |
| Unauthorized role | 403 Forbidden |
| Valid token + permission | Request succeeds |
Automated tests are particularly important for authentication because small security regressions can have significant consequences.
Production-Ready FastAPI Authentication Architecture
For a larger project, avoid putting everything into main.py.
A cleaner architecture might look like:
app/
│
├── main.py
│
├── core/
│ ├── config.py
│ └── security.py
│
├── models/
│ └── user.py
│
├── schemas/
│ ├── user.py
│ └── auth.py
│
├── routers/
│ ├── auth.py
│ └── users.py
│
├── services/
│ └── auth.py
│
└── database/
└── connection.py
This separation makes the authentication system easier to test, maintain, and extend.
FastAPI JWT Authentication Checklist
Before deploying your authentication system, check the following:
- Passwords are hashed securely.
- JWT secrets are stored outside source code.
- Access tokens expire.
- HTTPS is enabled.
- JWT algorithms are explicitly configured.
- Sensitive information is excluded from tokens.
- Protected endpoints validate tokens.
- Authorization checks are implemented where required.
- Refresh tokens are securely designed if used.
- Authentication failures return appropriate status codes.
- Rate limiting or abuse protection is considered for login endpoints.
- Authentication logic has automated tests.
- Dependencies are kept updated.
- Production secrets are managed securely.
Frequently Asked Questions
1. What is JWT authentication in FastAPI?
JWT authentication in FastAPI is a token-based authentication approach where the server generates a signed JSON Web Token after successful login. The client then sends the token with subsequent requests to protected API endpoints.
2. How do I create a JWT token in FastAPI?
You can use a JWT library such as PyJWT and encode claims with a secure secret key.
token = jwt.encode(
{"sub": "user@example.com"},
SECRET_KEY,
algorithm="HS256"
)
In production, include an appropriate expiration time and keep the secret key outside your source code.
3. Where should I store the JWT secret in FastAPI?
The secret should generally be stored in environment configuration or a dedicated secrets-management service rather than directly inside your Python source code.
Never commit production secrets to a public Git repository.
4. Is JWT authentication secure?
JWT can be secure when implemented correctly, but JWT itself does not automatically make an application secure.
Security depends on password hashing, secret management, token expiration, HTTPS, token storage, validation, authorization, and other application-level controls.
5. Should JWT access tokens expire?
Yes. Access tokens should generally have a limited lifetime.
For applications requiring longer sessions, a short-lived access token can be combined with a securely implemented refresh-token mechanism.
6. Can I use FastAPI JWT authentication with PostgreSQL or MongoDB?
Yes. JWT authentication is independent of the underlying database.
You can store users in PostgreSQL, MySQL, MongoDB, SQLite, or another database while using the same general authentication architecture.
7. What is the difference between authentication and authorization?
Authentication verifies who the user is.
Authorization determines what that authenticated user is allowed to access or modify.
For example, logging in proves that someone is an authenticated user, while checking whether they have an admin role determines whether they can access an admin endpoint.
8. Is JWT better than session-based authentication?
Neither approach is universally better.
JWT can be convenient for stateless APIs and distributed systems, while server-side sessions can make revocation and session management straightforward.
The right choice depends on your application’s architecture, clients, security requirements, and operational needs.
Conclusion
Building authentication with FastAPI and JWT involves more than simply generating a token after login.
A reliable authentication system should securely hash passwords, validate credentials, generate short-lived access tokens, verify JWT signatures and expiration, protect API routes with dependencies, and separate authentication from authorization.
The basic architecture is straightforward:
Register
│
▼
Hash Password
│
▼
Store User
│
▼
Login
│
▼
Verify Password
│
▼
Generate JWT
│
▼
Client Sends Bearer Token
│
▼
FastAPI Validates JWT
│
▼
Protected Resource
