What is JWT? A Complete Guide to JSON Web Tokens

What is JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact, self-contained way to securely transmit information between parties as a JSON object. JWTs are the dominant token format in modern web applications, used for everything from user authentication and API authorization to secure data exchange between microservices.

How JWT Authentication Works

JWT authentication follows a stateless pattern that eliminates the need for server-side session storage. Understanding this flow is key to understanding why JWTs have become the default choice for modern API security.

The Authentication Flow

1. User logs in — The client sends credentials (username and password) to the authentication server.
2. Server creates a JWT — The server validates the credentials, creates a JWT containing the user's identity and permissions, signs it with a secret or private key, and returns it to the client.
3. Client stores the token — The client stores the JWT, typically in localStorage, sessionStorage, or an HTTP-only cookie.
4. Client sends the token with each request — For every subsequent API request, the client includes the JWT in the Authorization header using the Bearer scheme: Authorization: Bearer <token>.
5. Server verifies the token — The server verifies the JWT signature, checks the expiration time, and extracts the user claims to authorize the request.
6. No session lookup required — Because the JWT contains all necessary information, the server does not need to query a database or cache to identify the user.

Why This Matters

Traditional session-based authentication stores session IDs in the server's memory or database. Each authenticated request requires a lookup. JWTs eliminate this lookup — the token itself proves the user's identity. This makes JWT-based systems inherently scalable because any server in a cluster can verify a token without shared session state.

JWT vs Session-Based Authentication

| Aspect | JWT Authentication | Session-Based Authentication | |--------|--------------------|------------------------------| | Storage | Client-side (in the token) | Server-side (in memory or DB) | | Scalability | No shared session store needed | Requires shared session store across instances | | Cross-domain | Works naturally across domains | Difficult to share sessions | | Mobile-friendly | Yes (no cookies required) | Requires cookie support | | Revocation | Difficult (until token expires) | Easy (delete session from store) | | Payload size | Larger per request (token in header) | Minimal (just session ID) |

Why JWT Is Used for API Security

The characteristics that make JWT suitable for authentication also make it ideal for securing APIs.

Stateless and Scalable

Every JWT carries all the information the server needs to authorize a request. There is no session database to query, no cache to check, no state to synchronize across servers. Load balancers can route requests to any server instance without coordination.

Cross-Domain and Cross-Origin

JWT works naturally across different domains and origins. A token issued by auth.example.com can be used to access api.example.com and admin.example.com. This makes JWT the foundation of single sign-on (SSO) systems.

Fine-Grained Authorization

The JWT payload can include custom claims for roles, permissions, and organization memberships:

{
  "sub": "user_abc123",
  "role": "admin",
  "permissions": ["read:users", "write:users", "delete:users"],
  "org_id": "org_xyz789",
  "iat": 1516239022,
  "exp": 1516325422
}

The API server reads these claims directly from the token without any additional lookup.

JWT for Single Sign-On (SSO)

Single sign-on is one of the most common JWT use cases. In a typical SSO architecture:

1. A user logs into the identity provider (IdP) — such as Auth0, Okta, or Keycloak.
2. The IdP issues a JWT signed with its private key.
3. The user presents this JWT to multiple applications.
4. Each application verifies the signature using the IdP's public key.
5. Each application trusts the token without communicating with the IdP on every request.

This pattern enables a single login to grant access to dozens of services — email, file storage, project management, HR systems — without each service implementing its own login flow.

JWT Security Best Practices

While JWT provides strong foundations for API security, correct implementation is essential.

Keep Tokens Short-Lived

Set the exp (expiration) claim to a short duration — 15 minutes to 1 hour for access tokens. Use longer-lived refresh tokens (days or weeks) to obtain new access tokens without requiring the user to re-authenticate.

Use HTTPS Always

JWT does not encrypt its payload. Anyone who intercepts the token can decode and read its contents. Always transmit JWTs over HTTPS to prevent interception.

Validate Everything

Always verify the signature, check that the token has not expired, confirm the aud (audience) matches your application, and reject tokens with unexpected algorithms.

Store Tokens Securely

On the client side, store JWTs in HTTP-only cookies when possible, or in memory for single-page applications. Avoid localStorage for tokens that provide access to sensitive data.

Common JWT Misconceptions

"JWT is encrypted." — No. JWT is signed, not encrypted. The payload is base64url-encoded, which is reversible. JWE (JSON Web Encryption) provides encryption, but it is a separate specification not covered by standard JWT.

"JWT prevents CSRF." — Not by itself. JWT in an Authorization header helps, but if the token is in a cookie, CSRF protection is still needed.

"JWT is only for authentication." — JWT is used for authentication, but also for authorization data exchange, stateless sessions, and secure information sharing between services.

Decode and Explore JWT Online

Use the JWT decoder tool to inspect any JSON Web Token. Paste your token and see the decoded header, payload, and signature algorithm instantly. The tool helps you understand what data your tokens carry and verify that they are structured correctly.