> For the complete documentation index, see [llms.txt](/docs/llms.txt)

# Understanding JSON Web Tokens (JWTs)

A high level view of Json Web Tokens (JWT).

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**[#](#what-youll-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?**[#](#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**[#](#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.

![Diagram of a simple application.](/img/blogs/understanding-jwt/simple-application.png)

### **Enter JWTs**[#](#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**[#](#breaking-down-a-jwt)

![A breakdown of the elements in a JSON web token JWT.](/img/blogs/understanding-jwt/jwt-breakdown.png)

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?**[#](#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?**[#](#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**[#](#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](/docs/apis/jwt). Make sure you [store them securely](/docs/apis/jwt/retrieve-refresh-tokens#response-1) and choose the right expiration and [refresh](/docs/apis/jwt/refresh-a-jwt) strategies for your use case.

## **Further Reading & Resources**[#](#further-reading--resources)

[Play](https://youtube.com/watch?v=QaOKmhD-7_Y)

Want to dive deeper? Here are some helpful links:

*   [JWT.io](https://jwt.io/)
*   [FusionAuth JWT Overview](/docs/apis/jwt)
*   [OWASP on Token Storage](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html)