Why JWT matters for APIs in Spring Boot - Why It Works This Way

Overview - Why JWT matters for APIs

What is it?

JWT stands for JSON Web Token. It is a way to securely share information between a client and a server as a compact, URL-safe string. APIs use JWT to verify who is making a request without needing to store session data on the server. This helps keep communication safe and efficient.

Why it matters

Without JWT, APIs would need to keep track of every user session on the server, which can slow down the system and make scaling difficult. JWT allows APIs to trust requests by checking the token's signature, making it easier to build fast, secure, and scalable applications. This means users can safely access services without repeated logins or heavy server memory use.

Where it fits

Before learning JWT, you should understand basic web APIs, HTTP requests, and authentication concepts like sessions and cookies. After JWT, you can explore advanced API security topics like OAuth2, OpenID Connect, and token refresh strategies.

Mental Model

Core Idea

JWT is a secure, self-contained token that proves who you are to an API without needing the server to remember you.

Think of it like...

Imagine a concert ticket that shows your name and seat number, and has a special stamp proving it's real. You show this ticket at the door, and the staff trusts it without calling the ticket office every time.

┌───────────────┐
│   Header      │
│ (algorithm,  │
│  token type)  │
├───────────────┤
│   Payload     │
│ (user info,  │
│  claims)      │
├───────────────┤
│ Signature     │
│ (signed hash) │
└───────────────┘

Build-Up - 6 Steps

1

Foundation

What is JWT and its parts

Concept: JWT is made of three parts: header, payload, and signature.

The header tells what algorithm is used to sign the token. The payload contains user data and claims like user ID or roles. The signature is created by combining the header and payload and signing them with a secret key to prevent tampering.

Result

You get a token string like 'header.payload.signature' that can be sent with API requests.

Understanding JWT's structure helps you see how it carries information securely and why each part is important.

2

Foundation

How APIs use JWT for authentication

Concept: APIs check the JWT sent by clients to decide if the request is allowed.

When a user logs in, the server creates a JWT and sends it to the client. The client includes this token in the Authorization header of future API requests. The API verifies the token's signature and reads the payload to identify the user and their permissions.

Result

The API can trust the request without storing session data, making authentication stateless.

Knowing this flow shows why JWT is efficient and scalable for API security.

3

Intermediate

Why JWT is stateless and scalable

🤔Before reading on: do you think JWT requires the server to store user sessions or not? Commit to your answer.

Concept: JWT tokens carry all needed info, so servers don't keep session records.

Because the token contains user data and is signed, the server just verifies it without looking up session info. This means servers can handle many users without extra memory or database calls for sessions.

Result

APIs can scale easily across many servers or cloud instances without syncing session data.

Understanding statelessness explains why JWT is popular for modern distributed systems.

4

Intermediate

Security risks and how JWT protects

🤔Before reading on: do you think JWT tokens can be changed by clients without detection? Commit to yes or no.

Concept: JWT uses a signature to detect if the token was altered.

If someone changes the payload or header, the signature won't match when the server checks it. This prevents attackers from forging tokens. However, if the secret key is leaked or weak, security breaks down.

Result

APIs reject tampered tokens, keeping user data and access safe.

Knowing JWT's signature role helps you understand both its strengths and what to protect in production.

5

Advanced

JWT expiration and refresh strategies

🤔Before reading on: do you think JWT tokens last forever or have a limited lifetime? Commit to your answer.

Concept: JWT tokens include expiration times to limit how long they are valid.

Tokens have an 'exp' claim that tells when they expire. After expiration, clients must get a new token, often using a refresh token. This balances security (short-lived tokens reduce risk) and usability (refresh tokens avoid frequent logins).

Result

Users stay logged in smoothly while APIs remain secure against stolen tokens.

Understanding token lifecycle is key to building secure, user-friendly APIs.

6

Expert

JWT pitfalls and best practices in production

🤔Before reading on: do you think storing sensitive data inside JWT payload is safe? Commit to yes or no.

Concept: JWT payload is base64 encoded but not encrypted, so sensitive data should not be stored there.

Anyone with the token can decode the payload and see its contents. Best practice is to keep sensitive info out of JWT and use HTTPS to protect tokens in transit. Also, use strong secret keys and rotate them periodically.

Result

APIs remain secure and user data private even if tokens are intercepted.

Knowing JWT's limits prevents common security mistakes that can expose user data.

Under the Hood

JWT works by encoding the header and payload as base64 strings, then creating a signature by hashing these with a secret key using an algorithm like HMAC SHA256. When the server receives a token, it decodes the header and payload, recalculates the signature with the secret, and compares it to the token's signature. If they match, the token is valid and untampered. This process requires no server-side storage of user sessions, enabling stateless authentication.

Why designed this way?

JWT was designed to solve the problem of scalable, stateless authentication for APIs and distributed systems. Traditional session storage requires servers to keep track of users, which is hard to scale. JWT's self-contained tokens allow any server to verify identity without shared session stores. The compact, URL-safe format makes it easy to pass tokens in HTTP headers or URLs. Alternatives like opaque tokens require server storage, so JWT was chosen for its statelessness and flexibility.

Client                        Server
   │                             │
   │--- Login request ---------->│
   │                             │
   │<-- JWT token -------------- │
   │                             │
   │--- API request with JWT --->│
   │                             │
   │   Decode & verify token     │
   │<----------------------------│
   │                             │
   │<-- API response ------------ │

Myth Busters - 4 Common Misconceptions

Quick: Does JWT encrypt the data inside the token? Commit to yes or no.

Common Belief: JWT tokens are encrypted, so no one can read the data inside.

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

Why it matters: Storing sensitive info in JWT payload can expose it if tokens are intercepted or leaked.

Quick: Do you think JWT tokens can be invalidated before they expire? Commit to yes or no.

Common Belief: You can immediately revoke a JWT token anytime from the server.

Reality: JWT tokens are stateless and cannot be revoked unless you keep a blacklist or change the secret key.

Why it matters: Without revocation, stolen tokens remain valid until expiration, risking unauthorized access.

Quick: Does sending JWT over HTTP instead of HTTPS keep it safe? Commit to yes or no.

Common Belief: JWT tokens are secure on their own, so HTTP is fine.

Reality: JWT tokens must be sent over HTTPS to prevent interception by attackers.

Why it matters: Sending tokens over HTTP exposes them to theft, allowing attackers to impersonate users.

Quick: Can you store large amounts of data inside a JWT token? Commit to yes or no.

Common Belief: JWT tokens can hold any amount of user data safely.

Reality: JWT tokens should be small because they are sent with every request; large tokens slow down communication.

Why it matters: Oversized tokens reduce API performance and increase network load.

Expert Zone

1

JWT signature verification can be vulnerable if the algorithm is not strictly checked, leading to attacks like algorithm confusion.

2

Using asymmetric keys (RSA/ECDSA) for signing JWTs allows public verification without exposing the private signing key, improving security in distributed systems.

3

Refresh tokens should be stored securely and separately from access tokens to prevent replay attacks and token theft.

When NOT to use

JWT is not ideal when you need immediate token revocation or store large session data. In such cases, traditional server-side sessions or opaque tokens with a centralized store are better.

Production Patterns

In production, JWTs are often combined with OAuth2 for delegated access, use short-lived access tokens with refresh tokens, and are transmitted only over HTTPS with secure storage on clients. Servers validate tokens on every request without session lookups, enabling horizontal scaling.

Connections

OAuth2

JWT is often used as the token format within OAuth2 authorization flows.

Understanding JWT helps grasp how OAuth2 securely passes user identity and permissions between services.

Public Key Cryptography

JWT can use asymmetric keys to sign tokens, linking it to public/private key cryptography principles.

Knowing public key cryptography explains how JWTs can be verified by many servers without sharing secret keys.

Physical Access Control Systems

JWT tokens function like digital access badges that prove identity without needing a central check every time.

Seeing JWT as a digital badge clarifies how stateless authentication works in distributed environments.

Common Pitfalls

#1 Storing sensitive user data like passwords inside JWT payload.

Wrong approach:

{"sub":"user123","password":"secret123"}

Correct approach:

{"sub":"user123","role":"user"}

Root cause:

Misunderstanding that JWT payload is encrypted rather than just encoded.

#2 Not verifying the JWT signature on the server.

Wrong approach:

Accepting JWT payload data without checking the signature.

Correct approach:

Always verify JWT signature using the secret or public key before trusting payload.

Root cause:

Assuming the token is trustworthy without cryptographic verification.

#3 Sending JWT tokens over plain HTTP.

Wrong approach:

curl http://api.example.com/data -H "Authorization: Bearer "

Correct approach:

curl https://api.example.com/data -H "Authorization: Bearer "

Root cause:

Ignoring the need for encrypted transport to protect tokens in transit.

Key Takeaways

JWT is a compact, self-contained token that securely carries user identity and claims for APIs.

It enables stateless authentication, allowing APIs to scale without storing session data.

JWT tokens are signed but not encrypted, so sensitive data should never be stored inside them.

Proper signature verification and HTTPS transport are essential to keep JWT-based APIs secure.

Understanding JWT's lifecycle, including expiration and refresh, is key to building user-friendly and safe APIs.