Understanding JSON Web Tokens (JWTs)

Today, you’ll be diving into the world of JSON Web Tokens (JWTs) — and keeping it simple. Whether you’re just getting started with APIs, microservices, or modern authentication, this post will give you a solid foundation on what JWTs are, how they work, and why they’re useful.

What You’ll Cover

Here’s a quick overview of what you’ll explore:

• What JWTs are and why they matter
• A real-world problem they solve
• How JWTs are structured
• Best practices for storing them
• What refresh tokens are and how they help
• Key takeaways and resources

Let’s get into it.

What Are JWTs — And Why Should You Care?

JWT stands for JSON Web Token — and it’s pronounced “jot.”

These little guys are used all over the web, especially in authentication systems. Here’s why they’re so popular:

• They’re secure: JWTs include a signature that proves the data hasn’t been tampered with. Think of it like getting a notarized document — it validates that the information has not been changed.
• They’re stateless: Servers don’t need to remember anything about the user between requests. The token itself carries all the necessary info.
• They’re portable: JWTs are great for APIs and microservices, where lightweight, stateless communication is ideal.
• They’re supported widely: Identity providers like FusionAuth, Auth0, Firebase, and Okta issue JWTs, and they’re supported across virtually every programming language.

The Problem JWTs Help Solve

Let’s say you have two separate APIs — a User API that handles authentication, and a ToDo API for managing tasks. You want a client (like a mobile app or frontend) to interact with both. The User API has secure access to the Users database, but you don’t want the Todo API to have direct access to it.

The challenge? You need a secure way for the client to prove its identity to each API — without duplicating authentication logic.

Enter JWTs

Here’s how JWTs solve the problem:

1. There is a private signing key on the server and a corresponding public signing key on the client.
2. The client first contacts the User API.
3. The User API authenticates the user and creates a signed JWT using the private key.
4. The client sends that signed JWT to the ToDo API when it makes requests.
5. The ToDo API uses the public key to verify that the JWT is authentic and hasn’t been altered.

This is known as asymmetric signing — and it ensures security without having to share secrets between services.

Breaking Down a JWT

A JSON Web Token has three parts:

1. Header – Contains metadata, like which algorithm was used to sign the token.
2. Payload – The main content of the token. This includes claims, which are key-value pairs. Some are standardized (like iss for issuer or exp for expiration), while others can be custom.
3. Signature – Created by signing the header and payload together. This is what guarantees the token’s integrity.

If the data is changed, the signature won’t match — and the token will be rejected.

Where Should You Store JWTs?

Security is everything when it comes to tokens. Here’s where not to put them:

• ❌ LocalStorage or sessionStorage in the browser: These are accessible by JavaScript, which means they’re vulnerable to XSS attacks.

Here’s where you should store them:

• ✅ HttpOnly, secure cookies: These can’t be accessed by JavaScript, making them much safer. They’re also sent automatically with each request — perfect for session-based auth.
• ✅ Secure storage on mobile devices: Use Keychain (iOS) or Keystore (Android). These are built specifically to protect sensitive data.

Bottom line: Store your tokens like they’re the keys to your house — because they basically are.

What About Refresh Tokens?

JWTs usually expire after a short time (for security reasons). But it’s annoying to users to have to log in every time because their token hasn’t refreshed.

That’s where refresh tokens come in:

1. When the JWT expires, the ToDo API rejects it.
2. The client sends a refresh token to the User API.
3. The User API verifies the refresh token and returns a new JWT.
4. The client continues on its merry way.

This flow keeps the user authenticated without constant re-login prompts.

Wrapping Up

JSON Web Tokens are:

• Secure: when the cryptographic signature is verified, and all critical claims (expiration, issuer, and audience) are validated
• Scalable: perfect for stateless systems like APIs
• Useful: when used thoughtfully, they make auth fast and efficient

But like any tool, JWTs should be used wisely. Make sure you store them securely and choose the right expiration and refresh strategies for your use case.

Further Reading & Resources

Want to dive deeper? Here are some helpful links:

• JWT.io
• FusionAuth JWT Overview
• OWASP on Token Storage