Deepika Pusala

Posted on Nov 11

Authentication Basics (JWT) & FastAPI Security: A Beginner-Friendly Guide 🔐

#fastapi #python #security #authentication

🔐 Authentication Basics (JWT) & FastAPI Security

Authentication is not just a login page. 🙅‍♀️

It is about understanding how a backend identifies a user, verifies their identity, issues a token, and protects private API endpoints.

In this guide we'll learn everything from absolute zero:

✅ How JWT works internally
✅ What OAuth2PasswordBearer actually does
✅ Why password hashing is necessary
✅ How Depends() makes authentication reusable
✅ How all these pieces connect in a real React + FastAPI + PostgreSQL project (my Social Feed app)

Simple examples, real-world analogies, Python code and execution flows. No assumed knowledge. Let's go! 🚀

📚 Table of Contents

Authentication vs Authorization
Why do we need authentication?
Token-based authentication
What is JWT?
JWT issuing and verification
PyJWT and python-jose
What is OAuth2?
What is OAuth2PasswordBearer?
What is Depends()?
Password hashing (and why plaintext is a crime)
Passlib, bcrypt and Argon2id
Building the complete FastAPI auth system
Full execution flow
Expiry, access tokens, refresh tokens and logout
JWT vs session-based authentication
HTTP status codes
Common security mistakes
Architecture of a real FastAPI project
Interview questions
Quick quiz and final revision

1️⃣ Authentication vs Authorization

These two words sound similar, but they mean different things.

Imagine Instagram 📸. You open it and enter:

Email: deepika@gmail.com
Password: mypassword123

Instagram checks whether these credentials belong to a registered user. That's Authentication.

Now you're logged in and you try to edit someone else's profile. Instagram checks whether you have permission to do that. That's Authorization.

Concept	Meaning	Example
🪪 Authentication	Who are you?	Verify your login
🚦 Authorization	What can you do?	Can you delete this post?

🧠 Remember: Authentication = identity verification. Authorization = permission checking. Authentication usually happens first, authorization follows.

2️⃣ Why do we need authentication?

Suppose you build a social media app using:

⚛️ React frontend
⚡ FastAPI backend
🐘 PostgreSQL database

Your API has these endpoints:

GET    /feed
POST   /posts
DELETE /posts/15
GET    /users/10

What if anyone can call DELETE /posts/15? 😱 Anyone could delete anyone's post!

The backend needs a way to answer:

Who is making this request?
Are they logged in?
Is their identity valid?
Are they allowed to do this operation?

That's exactly what authentication (and authorization) solves.

3️⃣ What is token-based authentication?

A token is a piece of data that represents a user's authenticated session or identity.

Think of a movie theatre 🎬:

You buy a ticket.
The ticket is given to you.
You show it at the entrance.
Staff verifies it.
You're allowed inside.

You don't buy a new ticket for every section of the theatre. Same idea here:

User enters email and password.
Backend verifies the credentials.
Backend generates a token.
Frontend stores the token.
Frontend sends the token with every later request.
Backend verifies the token before allowing access.

After a successful login the backend returns something like:

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.example.signature",
  "token_type": "bearer"
}

And the frontend sends it back on future requests:

GET /feed
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.example.signature

3.1 🏷️ What is the `Authorization` header?

HTTP requests can carry headers, extra information about the request.

GET /profile
Authorization: Bearer abc123
Content-Type: application/json

Authorization → the header name
Bearer → tells the server "I'm giving you a bearer token"
abc123 → the token itself

A bearer token basically means: whoever holds this valid token can use it. 🎟️

⚠️ That's why tokens must be protected. If someone steals your token, they may be able to act as you.

3.2 🔄 The complete authentication flow

User logs in: React sends email and password to POST /login.
Backend verifies credentials: FastAPI fetches the user from PostgreSQL and checks the password hash.
Backend creates a JWT: it creates and signs a token containing claims.
Frontend receives the token: the response contains access_token and token_type.
Frontend makes another request: React sends Authorization: Bearer <token>.
FastAPI verifies the token: it checks the signature, expiry and claims.
Protected endpoint runs: if valid, the backend identifies the user and continues.

Now let's understand JWT itself. 👇

4️⃣ What is JWT (JSON Web Token)?

JWT stands for JSON Web Token. It's a compact format for transferring information between parties as a JSON-based, signed token.

A JWT looks like this:

xxxxx.yyyyy.zzzzz

Three parts separated by dots:

HEADER . PAYLOAD . SIGNATURE

Part	Contains
🧾 Header	Algorithm and token type
📦 Payload	User identity and token claims
✍️ Signature	Cryptographic proof of integrity

4.1 🧾 Header

{
  "alg": "HS256",
  "typ": "JWT"
}

alg → algorithm used to sign the token
HS256 → HMAC using SHA-256
typ → token type (JWT)

4.2 📦 Payload (claims)

Claims are statements about the user or the token.

{
  "sub": "101",
  "role": "user",
  "iat": 1794398200,
  "exp": 1794400000
}

Claim	Meaning
`sub`	Subject, usually the user identifier
`exp`	Expiration time
`iat`	Issued-at time
`iss`	Issuer of the token
`aud`	Intended audience
`jti`	Unique token identifier

These are standard registered claims. You can also add custom claims like role.

🚨 Very important: a JWT payload is NOT encrypted by default. Anyone holding the token can decode the header and payload!

So NEVER put these inside a JWT:

❌ Passwords
❌ Password hashes
❌ Secret API keys
❌ Sensitive personal information

A signed JWT gives you integrity, not confidentiality.

4.3 ✍️ Signature (the security-critical part)

The backend signs the token using a secret key. Conceptually:

Signature = HMAC-SHA256(
    encoded_header + "." + encoded_payload,
    SECRET_KEY
)

Imagine an attacker changes the payload from "sub": "user_101" to "sub": "admin_999". Without the secret key they cannot produce a matching signature, so verification fails. 🛡️

Encoding vs signing vs encryption:

📝 Encoding → makes data representable in a transport format
✍️ Signing → verifies integrity and authenticity
🔒 Encryption → hides data from unauthorized readers

JWTs using HS256 are signed, not encrypted.

5️⃣ JWT issuing and verification

🏭 Issuing

Creating and signing a JWT, usually right after a successful login.

token = create_access_token(user_id=101)

The function receives the identity, builds the payload, adds expiry, signs it and returns the JWT string.

🔍 Verification

Happens whenever a client sends the token to a protected API:

Extract the token
Verify the signature
Check the expiration
Read the user ID from the payload
Identify the corresponding user
Allow or reject the request

A token can be rejected because:

❌ Invalid signature
❌ Expired
❌ Malformed structure
❌ Required claims missing
❌ The user or session is no longer valid

💡 A valid signature does not automatically mean the account is still active. You may also need to check the user or session in your database.

6️⃣ PyJWT and python-jose

You never implement signing algorithms by hand. You use a library. 📦

Library	Purpose
`PyJWT`	Create, encode, decode and verify JWTs
`python-jose`	Create, encode, decode and verify JWTs

Both work with FastAPI. Older tutorials (and older FastAPI docs) use python-jose, while the more actively maintained PyJWT is what the current FastAPI documentation uses. I'll use PyJWT in this article:

pip install pyjwt

If you'd rather use python-jose:

pip install "python-jose[cryptography]"

(The function names encode / decode are almost identical, so everything below translates easily.)

6.1 🏭 Creating a JWT

import jwt
from datetime import datetime, timedelta, timezone

SECRET_KEY = "my-super-secret-key"   # ⚠️ demo only!
ALGORITHM = "HS256"

def create_access_token(user_id: int) -> str:
    expire = datetime.now(timezone.utc) + timedelta(minutes=30)
    payload = {
        "sub": str(user_id),
        "exp": expire,
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

Line-by-line:

SECRET_KEY: the secret used to sign the JWT. In real apps, never hardcode it. Load it from an environment variable. Make it strong, random and private. 🔑
ALGORITHM = "HS256": HMAC SHA-256. The same secret signs and verifies.
expire: the token dies 30 minutes from now. If a token is stolen but expires soon, the damage window is small. ⏳
"sub": str(user_id): by convention sub is a string, so we convert the ID.
jwt.encode(...): encodes the header and payload, creates the signature, joins the three parts and returns the JWT string. ✨

That's JWT issuing!

6.2 🔍 Verifying a JWT

import jwt
from jwt import InvalidTokenError

def verify_access_token(token: str):
    try:
        payload = jwt.decode(
            token,
            SECRET_KEY,
            algorithms=[ALGORITHM],   # 👈 explicit allow-list!
        )
    except InvalidTokenError:
        return None

    user_id = payload.get("sub")
    if user_id is None:
        return None
    return user_id

What jwt.decode() does:

Decodes the token
Checks the signature
Validates exp (it raises an error if the token has expired)
Rejects invalid tokens

⚠️ Notice algorithms=[ALGORITHM]. Always specify the algorithms you accept. Never blindly trust the algorithm declared by an incoming token.

7️⃣ What is OAuth2?

You might be thinking: "We learned JWT, why OAuth2? Aren't they the same?"

NOOO! 🙅 They're different things.

OAuth2 → an authorization framework. It describes how authorization is granted and how tokens are obtained.
JWT → a token format. It describes how a token can be represented.

OAuth2 doesn't require JWT. OAuth2 access tokens can also be opaque random strings.

7.1 🌍 Real-world example

You see a "Continue with Google" button and click it. Google authenticates you and your app receives authorization information through an OAuth-based flow. You never give your Google password to the third-party app. 🎉

One nuance:

OAuth2 primarily handles authorization.
OpenID Connect (OIDC), built on top of OAuth2, adds an identity layer for authentication. Google Sign-In generally uses OIDC.

7.2 ⚡ OAuth2 in FastAPI

FastAPI ships security utilities for common OAuth2-compatible patterns. The most important one is OAuth2PasswordBearer. 👇

8️⃣ What is `OAuth2PasswordBearer`?

OAuth2PasswordBearer is a FastAPI security dependency. Its job:

📍 Tell FastAPI where the token comes from
📤 Extract the bearer token from the Authorization header
📥 Hand that token to your dependency or endpoint
📖 Describe the OAuth2 security scheme in the OpenAPI docs (that green Authorize button in Swagger UI!)

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")

What does `tokenUrl="login"` mean?

It tells FastAPI (and the docs UI) that the endpoint used to obtain a token is POST /login.

What does it actually do?

Given this request:

GET /profile
Authorization: Bearer my-secret-token

it extracts my-secret-token (it strips the Bearer prefix).

It does NOT:

❌ Generate the JWT
❌ Verify the JWT signature
❌ Check the user's password
❌ Fetch the user from PostgreSQL
❌ Log the user in

🧠 OAuth2PasswordBearer only extracts the token. You still have to verify it yourself.

8.1 What if the token is missing?

If a request has no Authorization header, OAuth2PasswordBearer automatically responds with HTTP 401 Unauthorized. 🚫

9️⃣ What is `Depends()`?

Before building the full system we need dependency injection, another core FastAPI concept.

Imagine ten protected endpoints:

GET    /profile
GET    /feed
POST   /posts
DELETE /posts/10
POST   /comments
GET    /notifications
...

Every one needs authentication. Would you copy-paste the same token-checking code ten times? 😵 No way. FastAPI gives us:

Depends()

It means: "FastAPI, before running this endpoint, run this dependency and give me its result."

from fastapi import Depends, FastAPI

app = FastAPI()

def verify_user():
    return "Deepika"

@app.get("/profile")
def get_profile(user=Depends(verify_user)):
    return {"user": user}

What happens:

A request hits /profile
FastAPI sees Depends(verify_user)
FastAPI runs verify_user()
It returns "Deepika"
FastAPI passes that value into the user parameter
The endpoint runs

Response:

{
  "user": "Deepika"
}

That's Dependency Injection (DI). 💉

🔗 Connect the dots

Depends() → the dependency injection mechanism

OAuth2PasswordBearer → a dependency that extracts a bearer token

Your custom dependency (get_current_user) → verifies the token and identifies the user

Combining them

from fastapi import Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")

@app.get("/profile")
def get_profile(token: str = Depends(oauth2_scheme)):
    return {"received_token": token}

Incoming request
Authorization: Bearer abc123
        │
        ▼
Depends(oauth2_scheme)
        │  extracts "abc123"
        ▼
Endpoint receives token = "abc123"

But we haven't verified that abc123 is a valid JWT yet. That's coming up! 😉

🔟 Password hashing: why we can't store passwords directly

This is a HUGE real-world security concept. 🚨

A user registers with:

Email:    deepika@gmail.com
Password: deepika123

A beginner might store this directly:

id	email	password
1	deepika@gmail.com	deepika123

If your database is ever compromised, the attacker reads everyone's passwords. 💀 Applications must NEVER store plaintext passwords. They store password hashes.

10.1 What is hashing?

Hashing is a one-way transformation of input into a fixed-format output.

Input:  deepika123
Hash:   $argon2id$v=19$m=65536,t=3,p=4$...

(The exact output depends on the algorithm and a random salt.)

You cannot practically reverse a properly designed password hash back to the original password.

Hashing	Encryption
One-way	Reversible with the key
No decryption operation	Can be decrypted
Used for password verification	Used for confidentiality
Example: Argon2id	Example: AES

Password hashing is deliberately designed to make guessing expensive. 💸

10.2 What is bcrypt?

bcrypt is a password-hashing algorithm built specifically for password storage. Its key property is a configurable computational cost: the higher the cost, the more resources each hash needs, making bulk guessing slower.

10.3 🧂 What is a salt?

A salt is a random value added during password hashing.

Two users register with the same password:

User A: deepika123
User B: deepika123

Without salts, a deterministic scheme gives both the same hash. With unique random salts, their stored hashes differ.

Why it matters:

✅ Identical passwords get different hashes
✅ Precomputed rainbow-table attacks become much less useful
✅ Bulk password guessing gets harder

Good libraries generate and manage salts automatically. Don't roll your own.

10.4 ✅ How does verification work?

You do not "decrypt" the stored hash. Instead:

The library reads the algorithm and salt from the stored hash
Hashes the submitted password with those parameters
Compares the results securely
Returns True or False

REGISTRATION                      LOGIN
plain password                    entered password
     │                                 │
     ▼                                 ▼
  hashing                       verify against stored hash
     │                                 │
     ▼                                 ▼
 store the hash                    True / False

1️⃣1️⃣ What is Passlib?

Passlib is a Python library for password hashing and verification. It supports bcrypt, Argon2, PBKDF2 and more, so you never implement hashing by hand.

pip install "passlib[argon2]"

💡 I'm using Argon2id here, a modern, memory-hard algorithm (it needs both CPU and memory to compute, making guessing even more expensive). If you prefer bcrypt, use pip install "passlib[bcrypt]" and schemes=["bcrypt"]. Just make sure your passlib and bcrypt versions are compatible, since newer bcrypt releases have caused warnings or errors with older passlib.

from passlib.context import CryptContext

pwd_context = CryptContext(
    schemes=["argon2"],
    deprecated="auto",
)

CryptContext → Passlib's hashing configuration object
schemes=["argon2"] → our chosen algorithm
deprecated="auto" → lets Passlib flag older schemes that should be upgraded when users log in

Hash a password

def hash_password(password: str) -> str:
    return pwd_context.hash(password)

hashed = hash_password("deepika123")
print(hashed)   # a long Argon2id hash, NOT the original password

Verify a password

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

print(verify_password("deepika123", hashed))      # True ✅
print(verify_password("wrongpassword", hashed))   # False ❌

🧠 Passlib is the library; Argon2id / bcrypt is the algorithm. Don't mix them up!

The important lesson isn't "always use bcrypt". It's use a modern, slow, salted password-hashing algorithm, never plaintext and never ordinary SHA-256.

1️⃣2️⃣ Building a complete FastAPI authentication system 🏗️

Time to combine everything. We'll build:

✅ User registration
✅ Password hashing
✅ User login
✅ Password verification
✅ JWT generation
✅ Token extraction
✅ Token verification
✅ Protected endpoints
✅ A reusable authentication dependency

We'll use an in-memory dictionary so it's beginner-friendly. In a real app, PostgreSQL and a repository layer replace it.

12.1 📁 Folder structure

backend/
│
├── app/
│   ├── main.py
│   │
│   ├── api/
│   │   └── auth.py
│   │
│   ├── core/
│   │   └── security.py
│   │
│   ├── dependencies/
│   │   └── auth.py
│   │
│   ├── models/
│   │   └── user.py
│   │
│   └── schemas/
│       └── auth.py
│
└── requirements.txt

File	Responsibility
`core/security.py`	Password hashing, JWT creation and verification
`api/auth.py`	Login and registration endpoints
`dependencies/auth.py`	Extract token, verify token, identify current user
`models/user.py`	User database model
`schemas/auth.py`	Request and response validation
`main.py`	Creates the FastAPI application

This is separation of concerns: each file has one job. 🎯

Install what we need:

pip install fastapi uvicorn pyjwt "passlib[argon2]" python-multipart

(python-multipart is required because the login endpoint receives form data.)

12.2 🔐 Step 1: `core/security.py`

import os
from datetime import datetime, timedelta, timezone

import jwt
from jwt import InvalidTokenError
from passlib.context import CryptContext

# 🔑 Load from environment, NEVER hardcode in real projects
SECRET_KEY = os.environ.get("JWT_SECRET_KEY", "dev-only-change-me")
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

pwd_context = CryptContext(schemes=["argon2"], deprecated="auto")


# 🔒 Password helpers
def hash_password(password: str) -> str:
    return pwd_context.hash(password)


def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)


# 🎟️ JWT helpers
def create_access_token(user_id: int) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": str(user_id),
        "iat": now,
        "exp": now + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)


def decode_access_token(token: str) -> str | None:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    except InvalidTokenError:
        return None
    return payload.get("sub")

Four reusable operations in one place:

hash_password()
verify_password()
create_access_token()
decode_access_token()

12.3 🚪 Step 2: Registration and login routes (`api/auth.py`)

from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from pydantic import BaseModel

from app.core.security import (
    create_access_token,
    hash_password,
    verify_password,
)

router = APIRouter()

# 🧪 In-memory "database" (use PostgreSQL in real life!)
users: dict[str, dict] = {}


class RegisterRequest(BaseModel):
    email: str
    password: str


@router.post("/register", status_code=status.HTTP_201_CREATED)
def register(data: RegisterRequest):
    if data.email in users:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="User already exists",
        )

    users[data.email] = {
        "id": len(users) + 1,
        "email": data.email,
        "hashed_password": hash_password(data.password),
    }
    return {"message": "User registered successfully"}


@router.post("/login")
def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = users.get(form_data.username)  # username field = our email

    # Same error for "no such user" and "wrong password" 👇
    if not user or not verify_password(form_data.password, user["hashed_password"]):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect email or password",
            headers={"WWW-Authenticate": "Bearer"},
        )

    token = create_access_token(user["id"])
    return {"access_token": token, "token_type": "bearer"}

🧐 What is `OAuth2PasswordRequestForm`?

form_data: OAuth2PasswordRequestForm = Depends()

It's another FastAPI-provided dependency that extracts login credentials sent as form data:

form_data.username
form_data.password

The client submits:

POST /login
Content-Type: application/x-www-form-urlencoded

username=deepika@gmail.com&password=deepika123

Notice it says username even if your app identifies users by email. Just treat the username field as the email.

⚠️ Heads up: the OAuth2 Resource Owner Password Credentials grant is discouraged by modern OAuth security guidance for new systems. This form-based pattern is perfect for learning and for a first-party login API, but for production with external identity providers prefer Authorization Code with PKCE. A first-party login API can also simply accept a JSON request body.

12.4 🛡️ Step 3: Reusable authentication dependency (`dependencies/auth.py`)

from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer

from app.api.auth import users
from app.core.security import decode_access_token

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")


def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_error = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Invalid or expired token",
        headers={"WWW-Authenticate": "Bearer"},
    )

    user_id = decode_access_token(token)
    if user_id is None:
        raise credentials_error

    # ✅ Check the user still exists (real apps: query the DB / session)
    user = next((u for u in users.values() if str(u["id"]) == user_id), None)
    if user is None:
        raise credentials_error

    return user

Trace it:

oauth2_scheme → expects a bearer token in the Authorization header
Depends(oauth2_scheme) → FastAPI extracts the token and injects it
decode_access_token(token) → verifies the token and returns the user ID
if user_id is None → invalid or expired token means reject
We look the user up, because a valid signature doesn't prove the account is still active
Return the authenticated user

12.5 🔒 Step 4: Protect an endpoint (`main.py`)

from fastapi import Depends, FastAPI

from app.api.auth import router as auth_router
from app.dependencies.auth import get_current_user

app = FastAPI()
app.include_router(auth_router)


@app.get("/profile")
def get_profile(current_user: dict = Depends(get_current_user)):
    return {
        "message": "Welcome!",
        "user_id": current_user["id"],
        "email": current_user["email"],
    }

That one line:

current_user: dict = Depends(get_current_user)

does a LOT of work. Before /profile runs, FastAPI:

Calls get_current_user()
Extracts the token via oauth2_scheme
Verifies the JWT
Loads the user
Injects the user into your endpoint

✅ Success:

{
  "message": "Welcome!",
  "user_id": 1,
  "email": "deepika@gmail.com"
}

❌ Failure (the endpoint body never runs):

{
  "detail": "Invalid or expired token"
}

12.6 🧪 Try it!

Run the app:

uvicorn app.main:app --reload

Then open http://127.0.0.1:8000/docs, register a user, click Authorize (🔓) and log in. Swagger UI now automatically sends your bearer token. Or test with curl:

# 1. Register
curl -X POST http://127.0.0.1:8000/register \
  -H "Content-Type: application/json" \
  -d '{"email": "deepika@gmail.com", "password": "deepika123"}'

# 2. Login (form data!)
curl -X POST http://127.0.0.1:8000/login \
  -d "username=deepika@gmail.com&password=deepika123"

# 3. Call the protected route
curl http://127.0.0.1:8000/profile \
  -H "Authorization: Bearer <paste_access_token_here>"

⚠️ This is intentionally simplified. The in-memory users dict isn't shared between processes and disappears on restart. A real implementation uses database-backed users and sessions.

12.7 🚦 Bonus: Authorization (role checks)

Authentication tells you who. Now let's check what they can do, by building on get_current_user:

from fastapi import Depends, HTTPException, status

def require_admin(current_user: dict = Depends(get_current_user)):
    if current_user.get("role") != "admin":
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You don't have permission to do this",
        )
    return current_user


@app.delete("/posts/{post_id}")
def delete_post(post_id: int, admin: dict = Depends(require_admin)):
    return {"message": f"Post {post_id} deleted"}

Dependencies can depend on other dependencies. 🧩 That's what makes Depends() so powerful.

1️⃣3️⃣ Complete execution flow 🧭

Phase A: Registration 📝

User enters email + password
        │
        ▼
POST /register
        │
        ▼
hash_password()  →  plaintext becomes a secure hash
        │
        ▼
PostgreSQL stores: email + password hash

Phase B: Login 🔑

POST /login  (username + password)
        │
        ▼
Backend finds the user, verify_password()
        │
        ▼
create_access_token()  →  JWT created and signed
        │
        ▼
Frontend receives: access_token + "bearer"

Phase C: Accessing a protected endpoint 🚪

React requests /profile
Authorization: Bearer <JWT>
        │
        ▼
OAuth2PasswordBearer  →  extracts the JWT
        │
        ▼
get_current_user()  →  verifies token, identifies user
        │
        ▼
Depends(get_current_user)  →  injects the user into the endpoint
        │
        ▼
✅ Endpoint returns the user's profile

If you understand this flow, you understand the foundation of JWT authentication in FastAPI. 🏆

1️⃣4️⃣ Token expiry, refresh tokens and logout ⏰

Our JWT contains:

{
  "sub": "101",
  "exp": 1794400000
}

Suppose the token is created at 10:00 AM and expires at 10:30 AM:

10:15 AM request → ✅ valid, the request proceeds
10:45 AM request → ❌ expired, the backend rejects it, and the user needs a new access token

14.1 🎫 Access token

A credential presented to an API to access protected resources.

GET /feed
Authorization: Bearer <access_token>

Access tokens are short-lived, so a stolen one is only useful for a limited time (plus any extra revocation checks).

14.2 🔁 Refresh token

A credential used to get a new access token without asking for the password again.

Access token lifetime: 30 minutes
Refresh token lifetime: 7 days

When the access token expires:

Frontend sends the refresh token to a refresh endpoint
Backend validates it
Backend issues a new access token
The user keeps using the app seamlessly ✨

Refresh tokens are especially sensitive. Store them carefully, rotate them when used where appropriate, and make them revocable. For browser apps, a common approach is HttpOnly, Secure, properly configured SameSite cookies.

14.3 🚪 What about logout?

Traditional server-side sessions can be killed by deleting the session on the server. But a self-contained JWT stays cryptographically valid until it expires, even after the user clicks "Logout". The JWT doesn't magically know the user logged out. 🤔

Possible solutions:

Keep access tokens short-lived
Track or revoke sessions server-side
Use a token denylist when appropriate
Revoke refresh tokens
Rotate session credentials

This is why real-world systems often combine tokens with database-backed sessions.

1️⃣5️⃣ JWT vs Session-based authentication ⚔️

Both are widely used in production.

🗄️ Session-based

The backend creates a session in the database:

Session ID	User ID	Expires
abc123	101	7 days

On every request: the frontend sends the session ID → the backend looks it up → checks validity → identifies the user.

🎟️ JWT-based

The backend issues a signed JWT containing identity and expiry. On every request: the frontend sends the JWT → the backend verifies the signature → checks the claims → identifies the user.

JWT	Server-side session
Identity carried in token claims	Identity retrieved via session lookup
Can be verified without a DB lookup	Normally requires a session lookup
Revocation needs extra mechanisms	Revoked by invalidating the session
Self-contained token	Server maintains session state
Common in distributed APIs	Common in traditional web apps

⚖️ Neither is automatically better. The right choice depends on your architecture and security requirements.

💼 In my Social Feed project

My implementation actually uses database-backed sessions (7-day lifetime) with Argon2id for passwords, and SHA-256 hashing of a random session token for lookups. That's different from the JWT example above:

My session implementation	JWT implementation
Random session token	Structured JWT
Hash token for DB lookup	Cryptographically sign token
Database session lookup	Signature verification
Easy server-side revocation	Needs extra revocation strategy

🧠 Why is SHA-256 okay here? Because it's hashing a high-entropy random token, not a human-chosen password. Passwords need slow, salted algorithms like Argon2id or bcrypt. Random tokens don't, since they can't be guessed from a dictionary.

1️⃣6️⃣ HTTP status codes in authentication 📟

Code	Meaning	Example
`200`	OK	Successful login
`201`	Created	Successful registration
`400`	Bad Request	Invalid request
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Authenticated but lacks permission
`404`	Not Found	User doesn't exist
`422`	Validation Error	Invalid request schema
`500`	Internal Server Error	Unexpected backend failure

The most important distinction: `401` vs `403`

🪪 You try to enter an office without an ID card → 401
🚫 You show a valid ID card but try to enter the server room → 403

Authentication asks: is your identity valid? Authorization asks: do you have permission?

1️⃣7️⃣ Common security mistakes ⚠️

Mistake	Why it's dangerous
Storing plaintext passwords	A DB leak exposes passwords
Using plain SHA-256 for passwords	Too fast, easy to brute-force
Hardcoding JWT secrets	The secret leaks through source code
Never-expiring access tokens	Stolen tokens stay useful forever
Putting passwords in the JWT payload	The payload can be decoded
Accepting any JWT algorithm	Serious verification vulnerabilities
Not checking token expiration	Expired credentials may be accepted
Detailed login errors	Reveals which accounts exist
Storing tokens carelessly	XSS or other attacks can steal them
Forgetting HTTPS	Credentials and tokens can be intercepted

📖 A few more terms worth knowing

HTTPS → encrypts communication between browser and server
CORS → controls which browser origins may access your backend (it is not authentication!)
XSS → malicious scripts executing in a user's browser
CSRF → tricks a browser into making an unwanted authenticated request
Brute-force attack → repeatedly guessing passwords
Rate limiting → restricts excessive requests, like repeated login attempts

🍪 Where should the frontend store tokens?

localStorage is readable by JavaScript, so it's exposed if an XSS vulnerability exists. HttpOnly cookies can't be read by JavaScript, but cookie-based auth needs proper CSRF protection. There's no free lunch. Design it carefully. 🧠

1️⃣8️⃣ How this connects to real FastAPI architecture 🏛️

┌──────────────────────────────────────────────┐
│  API / Router layer                          │
│  Receives login and protected requests       │
│  e.g. auth.py, users.py                      │
├──────────────────────────────────────────────┤
│  Dependency layer                            │
│  Extracts token, identifies the user         │
│  e.g. get_current_user()                     │
├──────────────────────────────────────────────┤
│  Security layer                              │
│  Hash/verify passwords, issue/verify JWTs    │
│  e.g. security.py                            │
├──────────────────────────────────────────────┤
│  Service layer                               │
│  Authentication business logic               │
│  e.g. auth_service.py                        │
├──────────────────────────────────────────────┤
│  Repository / Database layer                 │
│  Fetch users, create sessions, run queries   │
│  e.g. user_repository.py, session_repository.py │
└──────────────────────────────────────────────┘

🧼 Principle: keep the router thin. Delegate business logic to services and database work to repositories.

1️⃣9️⃣ Interview questions & answers 🎤

Q1. What is authentication?
Verifying the identity of a user before allowing access to protected resources.

Q2. What is JWT?
JSON Web Token, a compact, signed token format used to transfer claims between parties.

Q3. What are the three parts of a JWT?
Header, payload and signature.

Q4. Is JWT encrypted?
Not by default. A typical signed JWT has an encoded header and payload plus a signature. The payload can be decoded by anyone.

Q5. What is OAuth2PasswordBearer?
A FastAPI security dependency that extracts a bearer token from the Authorization header and declares an OAuth2 security scheme in the API docs.

Q6. Does OAuth2PasswordBearer verify JWT signatures?
No. It only extracts the token. You need separate verification logic.

Q7. What is Depends()?
FastAPI's dependency injection mechanism, which lets reusable functions and resources be provided to endpoints.

Q8. What is password hashing?
A one-way transformation of a password into a secure stored form that can be verified later without storing the original.

Q9. What is bcrypt?
A password-hashing algorithm designed to make guessing computationally expensive.

Q10. What is a salt?
A random value included in password hashing so identical passwords produce different stored hashes.

Q11. Access token vs refresh token?
An access token accesses protected APIs. A refresh token obtains a new access token.

Q12. What happens when a JWT expires?
The backend rejects it. The client may use a valid refresh mechanism to get a new one.

Q13. JWT vs session authentication?
JWT carries signed claims the server can verify. Sessions store state on the server and look it up via a session ID.

Q14. Why not store passwords directly in PostgreSQL?
A database breach would expose real passwords. We store salted, computationally expensive hashes instead.

Q15. 401 vs 403?
401 means valid authentication is missing. 403 means you're authenticated but lack permission.

2️⃣0️⃣ Quick knowledge test 🧪

Answer without scrolling up! (Answers are below.)

1. What does OAuth2PasswordBearer actually do?

A) Generates a JWT
B) Extracts the bearer token from the Authorization header
C) Hashes the password
D) Connects to PostgreSQL

2. Which three parts make up a JWT?

A) Username, password, signature
B) Header, payload, signature
C) Request, response, token
D) Issuer, database, session

3. Why do we hash passwords?

A) To decrypt them later
B) To make login faster
C) To avoid storing plaintext passwords
D) To create JWTs

4. What does Depends() do in FastAPI?

A) Automatically injects dependency results
B) Creates database tables
C) Encrypts tokens
D) Starts Uvicorn

5. Is JWT payload encryption automatic?

A) Yes, always
B) No, ordinary signed JWTs are not encrypted
C) Only with HS256
D) Only with FastAPI

6. What happens when a JWT expires?

A) It becomes valid forever
B) The backend should reject it
C) It refreshes itself automatically
D) The database deletes the user

👀 Click to reveal answers

🧾 Final revision: everything in one place

Concept	What to remember
Authentication	Verifying who the user is
Authorization	Checking what the user can access
Token	Credential representing an authenticated session or identity
JWT	Signed token format containing claims
Header	Algorithm and token type
Payload	User identity and claims
Signature	Protects token integrity
OAuth2	Authorization framework
`OAuth2PasswordBearer`	Extracts the bearer token
`Depends()`	Dependency injection
Password hashing	Secure password storage
bcrypt	Password-hashing algorithm
Argon2id	Modern memory-hard password-hashing algorithm
Passlib	Python password-hashing library
Access token	Used to access protected resources
Refresh token	Used to obtain new access tokens
`get_current_user()`	Reusable dependency to identify the authenticated user

🎯 Final thoughts

Don't just memorize definitions. Be able to explain the complete journey:

A user clicks Login in React → FastAPI verifies the password hash → a token is issued → React sends it on every request → OAuth2PasswordBearer extracts it → get_current_user() verifies it → Depends() injects the user → the protected /feed endpoint runs. 🚀

If you can narrate that flow confidently, you truly understand authentication.

And remember: JWT-based and database-session-based authentication are different designs. Both are valid. Knowing which one your code uses, and why, is what separates memorizing from understanding. 💡