JWT token creation in FastAPI - Deep Dive

Overview - JWT token creation

What is it?

JWT token creation is the process of making a secure string called a JSON Web Token that proves who you are. It contains information like your user ID and is signed so others can trust it. This token is used to let users access protected parts of a website or app without logging in every time. It is a safe way to share identity and permissions between a client and a server.

Why it matters

Without JWT tokens, websites would need to check your username and password every time you do something, which is slow and risky. JWT tokens let servers trust users quickly and safely, improving speed and security. They also allow apps to work across different servers or services without sharing passwords. Without JWT, user sessions would be clunky and less secure, making online experiences worse.

Where it fits

Before learning JWT token creation, you should understand HTTP basics, how web servers and clients communicate, and basic Python programming. After JWT tokens, you can learn about OAuth, advanced security practices, and how to build full authentication systems in FastAPI or other frameworks.

Mental Model

Core Idea

A JWT token is a secure, signed package of user info that servers use to quickly verify identity without storing session data.

Think of it like...

Imagine a sealed envelope with your ID and permissions inside, stamped by a trusted official. Anyone who sees the envelope can trust what's inside without opening it because of the official stamp.

┌───────────────┐
│ JWT Token     │
├───────────────┤
│ Header        │  ← describes token type and signing method
├───────────────┤
│ Payload       │  ← contains user info and claims
├───────────────┤
│ Signature     │  ← verifies token authenticity
└───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding JWT Token Structure

Concept: Learn the three parts that make up a JWT token: header, payload, and signature.

A JWT token has three parts separated by dots: header, payload, and signature. The header tells what type of token it is and how it is signed. The payload contains user data like user ID or roles. The signature is created by combining the header and payload with a secret key to ensure no one changed the token.

Result

You can recognize a JWT token as three base64 strings separated by dots, each part serving a clear role.

Understanding the token's parts helps you see how JWTs carry data securely and why each part is important.

2

Foundation

Basics of Token Signing

Concept: Learn how signing a token with a secret key ensures it cannot be tampered with.

Signing means creating a special code (signature) from the header and payload using a secret key. This signature is like a lock that only the server can open. If someone changes the token, the signature won't match, so the server knows it's fake.

Result

Tokens signed with a secret key can be trusted by the server to be unchanged and authentic.

Knowing how signing works is key to trusting tokens and preventing attackers from faking user identity.

3

Intermediate

Creating JWT Tokens in FastAPI

🤔Before reading on: do you think JWT tokens are created manually by combining strings or by using libraries? Commit to your answer.

Concept: Use Python libraries to create JWT tokens easily and correctly in FastAPI.

FastAPI uses the PyJWT library to create tokens. You write a function that takes user info, creates a payload with expiration time, and calls jwt.encode() with a secret key and algorithm. This returns a token string you can send to users.

Result

You get a ready-to-use JWT token string that clients can use to prove their identity.

Using libraries avoids mistakes and ensures tokens are created securely and follow standards.

4

Intermediate

Adding Expiration to Tokens

🤔Before reading on: do you think JWT tokens last forever or can they expire? Commit to your answer.

Concept: Include an expiration time in the token payload to limit how long the token is valid.

Add a claim called 'exp' to the payload with a timestamp in the future. When the server checks the token, it rejects it if expired. This protects users if tokens are stolen or lost.

Result

Tokens automatically become invalid after a set time, improving security.

Expiration limits damage from stolen tokens and forces users to re-authenticate periodically.

5

Advanced

Secure Secret Management

🤔Before reading on: do you think the secret key should be hardcoded in code or stored securely? Commit to your answer.

Concept: Keep the secret key used for signing tokens safe and separate from code.

Store the secret key in environment variables or secure vaults, not in code files. This prevents attackers from stealing the key if code is leaked. Rotate keys periodically and use strong random strings.

Result

Your tokens remain secure because only your server knows the secret key.

Protecting the secret key is critical; if leaked, attackers can create fake tokens.

6

Expert

Handling Token Revocation and Refresh

🤔Before reading on: do you think JWT tokens can be revoked instantly or only expire naturally? Commit to your answer.

Concept: Implement ways to revoke tokens before expiration and refresh tokens securely.

JWTs are stateless, so servers don't store them. To revoke, keep a blacklist of tokens or use short expiration with refresh tokens. Refresh tokens are long-lived and used to get new JWTs. This balances security and usability.

Result

Users can be logged out instantly, and tokens stay secure without storing sessions.

Knowing how to revoke and refresh tokens solves the main limitation of JWT's statelessness in real apps.

Under the Hood

JWT tokens are base64-encoded JSON objects split into header, payload, and signature. The signature is created by hashing the header and payload with a secret key using algorithms like HMAC SHA256. When a server receives a token, it decodes the header and payload, recalculates the signature with its secret key, and compares it to the token's signature. If they match and the token is not expired, the token is valid. This process requires no server-side session storage, making JWT stateless.

Why designed this way?

JWT was designed to allow secure, stateless authentication across distributed systems without needing a central session store. This reduces server load and allows easy scaling. The use of JSON makes tokens easy to read and extend. Signing ensures token integrity and authenticity. Alternatives like server sessions require storing user data on the server, which is harder to scale and maintain.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Header JSON   │──────▶│ Base64 Encode │──────▶│ Encoded Header│
└───────────────┘       └───────────────┘       └───────────────┘

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Payload JSON  │──────▶│ Base64 Encode │──────▶│ Encoded Payload│
└───────────────┘       └───────────────┘       └───────────────┘

┌───────────────────────────────┐
│ Signature = HMACSHA256(secret, │
│ EncodedHeader + '.' + EncodedPayload) │
└───────────────────────────────┘

Encoded JWT = EncodedHeader + '.' + EncodedPayload + '.' + Signature

Myth Busters - 4 Common Misconceptions

Quick: Do you think JWT tokens are encrypted by default? Commit to yes or no.

Common Belief: JWT tokens are encrypted, so no one can read their contents.

Reality: JWT tokens are only signed, not encrypted. Anyone with the token can decode and read the payload data.

Why it matters: Assuming tokens are secret can lead to exposing sensitive info in the payload, risking user privacy.

Quick: Can JWT tokens be invalidated instantly by the server? Commit to yes or no.

Common Belief: JWT tokens can be revoked instantly like server sessions.

Reality: JWT tokens are stateless and cannot be revoked instantly unless extra measures like blacklists are used.

Why it matters: Not knowing this can cause security holes where stolen tokens remain valid until expiration.

Quick: Do you think the secret key can be shared with clients? Commit to yes or no.

Common Belief: The secret key used to sign JWT tokens can be shared with clients for verification.

Reality: The secret key must remain private on the server; clients only get the token, not the key.

Why it matters: Sharing the secret key breaks security, allowing attackers to forge tokens.

Quick: Is it safe to put passwords inside JWT payloads? Commit to yes or no.

Common Belief: It's fine to include passwords or sensitive secrets inside JWT payloads.

Reality: Sensitive data like passwords should never be inside JWT payloads because tokens are readable by anyone holding them.

Why it matters: Exposing passwords in tokens risks account compromise if tokens leak.

Expert Zone

1

JWT tokens can include custom claims beyond standard ones, but overloading payloads can increase token size and risk exposure.

2

Using asymmetric keys (RSA) for signing allows public verification without exposing the private key, useful in distributed systems.

3

Clock skew between client and server can cause valid tokens to be rejected; allowing small time leeway improves reliability.

When NOT to use

Avoid JWT tokens when you need immediate token revocation or store sensitive session data server-side. Use traditional server sessions or opaque tokens stored in databases instead.

Production Patterns

In production, JWT tokens are often short-lived with refresh tokens for usability. Secrets are stored securely in environment variables. Tokens are sent in HTTP headers with Bearer scheme. Middleware verifies tokens on each request to protect routes.

Connections

OAuth 2.0

JWT tokens are often used as access tokens within OAuth 2.0 flows.

Understanding JWT helps grasp how OAuth securely delegates access without sharing passwords.

Public Key Cryptography

JWT can use asymmetric signing algorithms that rely on public/private key pairs.

Knowing public key cryptography clarifies how JWTs can be verified by anyone with the public key but only signed by the private key holder.

Digital Certificates

JWT signatures and digital certificates both use cryptographic signatures to prove authenticity.

Recognizing this connection helps understand trust models in web security beyond just tokens.

Common Pitfalls

#1 Hardcoding the secret key in source code.

Wrong approach:

SECRET_KEY = "mysecret123" # directly in code

Correct approach:

import os
SECRET_KEY = os.getenv('SECRET_KEY') # loaded from environment

Root cause:

Beginners often put secrets in code for convenience, not realizing it risks exposure if code is shared.

#2 Not setting token expiration, creating tokens that never expire.

Wrong approach:

payload = {"user_id": 1}
token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")

Correct approach:

from datetime import datetime, timedelta
payload = {"user_id": 1, "exp": datetime.utcnow() + timedelta(minutes=30)}
token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")

Root cause:

Beginners forget to add expiration, leaving tokens valid forever and increasing security risk.

#3 Including sensitive info like passwords in the token payload.

Wrong approach:

payload = {"user_id": 1, "password": "mypassword"}

Correct approach:

payload = {"user_id": 1}

Root cause:

Misunderstanding that JWT payloads are readable by anyone with the token.

Key Takeaways

JWT tokens are secure, signed packages of user info that servers use to verify identity without storing sessions.

Tokens have three parts: header, payload, and signature; the signature ensures the token is authentic and unchanged.

Creating JWT tokens in FastAPI is done using libraries like PyJWT, which handle encoding and signing safely.

Always include expiration in tokens and keep the secret key secure to prevent misuse and attacks.

JWT tokens are stateless and cannot be revoked instantly without extra measures, so plan token lifetimes and refresh strategies carefully.