If you have ever logged into a web application, called a protected API, or implemented single sign-on, you have almost certainly encountered a JWT token — whether you realized it or not. JSON Web Tokens are one of the most widely used authentication mechanisms on the modern web, and understanding how they work is essential for any developer building secure applications.

Yet most developers treat JWTs as black boxes. They copy-paste a library, call jwt.sign(), and move on. That works until something breaks — until a token expires and users get locked out, until you find yourself debugging a 401 error at 2 AM, or until a security audit reveals that your tokens are leaking sensitive data in plaintext.

This guide explains everything you need to know about JWTs. What they are, how they are structured, how to decode them, when to use them, and what security pitfalls to avoid.

What Is a JWT Token#

A JSON Web Token (JWT) is an open standard (RFC 7519) for securely transmitting information between parties as a compact, URL-safe JSON object. The information in a JWT can be verified and trusted because it is digitally signed.

JWTs can be signed using a secret key (with the HMAC algorithm) or a public/private key pair (using RSA or ECDSA). When a token is signed, the recipient can verify that the content has not been tampered with. When a token is encrypted, the content is also hidden from third parties.

The most common use case is authentication. After a user logs in, the server issues a JWT. The client stores this token (typically in memory or an HTTP-only cookie) and sends it with every subsequent request. The server validates the token's signature and extracts the user's identity without needing to query a database or maintain server-side session state.

This is fundamentally different from traditional session-based authentication, where the server stores session data and the client holds only a session ID. With JWTs, the token itself carries the information.

The Three Parts of a JWT#

Every JWT consists of three parts, separated by dots:

xxxxx.yyyyy.zzzzz

Those three parts are the header, the payload, and the signature. Each part is Base64URL-encoded, which means you can decode them without any special tools — just a Base64 Encoder/Decoder will get you most of the way there, though a dedicated JWT Decoder handles the URL-safe variant and displays the result in a structured format.

Here is a real example of what a JWT looks like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

That looks intimidating, but it is just three JSON objects encoded in Base64URL and concatenated with dots. Let us break each part down.

Part 1: The Header#

The header typically contains two fields: the signing algorithm (alg) and the token type (typ).

json

{
  "alg": "HS256",
  "typ": "JWT"
}

This tells the recipient that the token is a JWT and was signed using HMAC-SHA256. Other common algorithms include RS256 (RSA with SHA-256), ES256 (ECDSA with SHA-256), and EdDSA (Edwards-curve Digital Signature Algorithm).

The header is Base64URL-encoded to produce the first part of the token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.

Part 2: The Payload#

The payload contains the claims — statements about the user and additional metadata. This is where the actual data lives.

json

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516242622
}

Claims fall into three categories:

Registered claims are predefined by the JWT specification. They are not mandatory but are recommended for interoperability:

iss (issuer) — who created the token
sub (subject) — who the token is about (usually a user ID)
aud (audience) — who the token is intended for
exp (expiration time) — when the token expires (Unix timestamp)
nbf (not before) — the token is not valid before this time
iat (issued at) — when the token was created
jti (JWT ID) — a unique identifier for the token

Public claims are defined by the developer but should use collision-resistant names (often URIs) to avoid conflicts.

Private claims are custom claims agreed upon between parties, like role, permissions, or tenant_id.

Here is the critical thing to understand: the payload is not encrypted. It is only encoded. Anyone who has the token can decode the payload and read its contents. Never put sensitive information — passwords, credit card numbers, social security numbers — in a JWT payload.

Part 3: The Signature#

The signature is what makes JWTs trustworthy. It is created by taking the encoded header, the encoded payload, and a secret key, then applying the algorithm specified in the header.

For HMAC-SHA256, the signature is computed like this:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

The signature serves two purposes. First, it verifies that the token was issued by someone who knows the secret key. Second, it ensures the token has not been modified. If anyone changes a single character in the header or payload, the signature will not match, and the token will be rejected.

For asymmetric algorithms like RS256, the server signs the token with a private key and anyone can verify it with the corresponding public key. This is particularly useful in microservice architectures where multiple services need to verify tokens but only one service (the auth server) should be able to create them.

How JWT Authentication Works in Practice#

Here is the typical flow when JWTs are used for authentication:

Step 1: The user sends their credentials (username and password) to the authentication endpoint.

Step 2: The server verifies the credentials. If valid, it creates a JWT containing the user's ID, roles, and an expiration time, then signs it with a secret key.

Step 3: The server sends the JWT back to the client.

Step 4: The client stores the token and includes it in the Authorization header of subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Step 5: For each request, the server extracts the token from the header, verifies the signature, checks the expiration time, and extracts the user's identity from the payload.

You can test this entire flow using an API Tester to see how authorization headers work with real endpoints.

How to Decode a JWT Token#

Decoding a JWT is straightforward because the payload is simply Base64URL-encoded, not encrypted. There are several ways to do it.

Using a Free Online Tool#

The fastest way is to paste your token into a JWT Decoder. It will instantly split the token into its three parts, decode the header and payload, show the claims in a readable format, and display the expiration status.

Using JavaScript#

javascript

function decodeJWT(token) {
  const parts = token.split(".");
  if (parts.length !== 3) {
    throw new Error("Invalid JWT format");
  }
 
  const header = JSON.parse(atob(parts[0].replace(/-/g, "+").replace(/_/g, "/")));
 
  const payload = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
 
  return { header, payload, signature: parts[2] };
}

Using Python#

python

import base64
import json
 
def decode_jwt(token):
    parts = token.split('.')
    # Add padding if needed
    payload = parts[1] + '=' * (4 - len(parts[1]) % 4)
    decoded = base64.urlsafe_b64decode(payload)
    return json.loads(decoded)

Using the Command Line#

bash

echo 'eyJzdWIiOiIxMjM0NTY3...' | \
  tr '_-' '/+' | \
  base64 -d 2>/dev/null | \
  python3 -m json.tool

Remember: decoding is not the same as verifying. Anyone can decode a JWT. Only someone with the secret key can verify that it is authentic.

Common JWT Use Cases#

API Authentication#

JWTs are the standard for securing REST APIs. The client obtains a token after authenticating and includes it in every API request. The server validates the token without maintaining session state, making this approach highly scalable.

Single Sign-On (SSO)#

JWTs enable SSO across multiple applications. A user logs in once with a central identity provider, receives a JWT, and can use that token to access any application that trusts the same issuer. This is how protocols like OAuth 2.0 and OpenID Connect work under the hood.

Microservice Communication#

In a microservice architecture, services need to verify the identity of callers. JWTs work well here because each service can independently verify a token using the public key, without making a network call to the auth service.

Information Exchange#

JWTs can be used to securely transmit information between parties. Because they can be signed, the recipient knows the sender is who they claim to be, and that the content has not been changed in transit.

Security Best Practices#

JWTs are powerful but can be dangerous if misused. Follow these practices to avoid common pitfalls.

Keep Tokens Short-Lived#

Set the exp claim to a short duration — 15 minutes for access tokens is a common choice. Use refresh tokens (stored securely, typically in HTTP-only cookies) to obtain new access tokens without requiring the user to log in again.

json

{
  "sub": "user123",
  "iat": 1711500000,
  "exp": 1711500900
}

That token expires after 15 minutes. If it is stolen, the window of exploitation is limited.

Never Store Sensitive Data in the Payload#

The payload is Base64URL-encoded, not encrypted. Anyone who intercepts the token can read its contents. Include only the minimum information needed — a user ID and role, not personal data.

Use Strong Signing Keys#

For HMAC-based algorithms, use a key that is at least 256 bits long and generated with a cryptographically secure random number generator. Never use simple strings like "secret" or "my-jwt-key". You can use a Hash Generator to create strong, random keys.

Always Validate the Signature#

Never skip signature verification. Some libraries have options to decode a token without verifying it — these should only be used for debugging, never in production.

Validate All Claims#

Check not just the signature but also the exp, iss, aud, and nbf claims. A valid signature on an expired token should still result in rejection.

Use HTTPS Everywhere#

JWTs transmitted over plain HTTP can be intercepted. Always use HTTPS in production. This is non-negotiable.

Choose the Right Algorithm#

Prefer RS256 or ES256 over HS256 in production environments where multiple services need to verify tokens. With asymmetric algorithms, only the auth server needs the private key. If using HS256, the same secret must be shared with every service that verifies tokens, increasing the risk of key compromise.

Common JWT Vulnerabilities#

The `alg: none` Attack#

Some JWT libraries support an alg: none option, which means the token has no signature. An attacker can modify the payload, set the algorithm to none, remove the signature, and send the token to a server that does not properly validate the algorithm. Always reject tokens with alg: none in production.

Algorithm Confusion#

If a server is configured to accept RS256 (asymmetric), an attacker might change the algorithm to HS256 (symmetric) and sign the token with the public key (which is often publicly available). If the server does not enforce the expected algorithm, it might accept the forged token. Always enforce the algorithm on the server side and do not let the token dictate which algorithm to use.

Token Sidejacking#

If JWTs are stored in localStorage, they are vulnerable to cross-site scripting (XSS) attacks. A malicious script can read the token and send it to an attacker. Use HTTP-only cookies with the Secure, SameSite, and HttpOnly flags set.

Missing Expiration#

Tokens without an exp claim are valid forever. If one is stolen, it grants permanent access. Always set an expiration time, and implement token revocation for critical scenarios (user logout, password change, compromised accounts).

Excessive Payload Size#

Every claim you add increases the token size, and the token is sent with every request. Large tokens increase bandwidth usage and can even exceed header size limits on some servers. Keep your payload minimal.

JWT vs. Sessions: When to Use Which#

JWTs are not always the right choice. Here is a quick comparison:

Choose JWTs when:

You need stateless authentication at scale
You are building a distributed system or microservice architecture
You need cross-domain authentication (SSO)
Your API serves mobile clients, SPAs, or third-party consumers

Choose sessions when:

You need the ability to instantly revoke access (logout)
You are building a traditional server-rendered application
Your application is a monolith with a single server
You need to store large amounts of session data

Many production systems use a hybrid approach: JWTs for short-lived access tokens combined with server-side refresh token storage for revocation capability.

Token Expiration and Refresh Flow#

A well-designed JWT system uses two types of tokens:

Access tokens are short-lived (5 to 15 minutes) and contain the user's identity and permissions. They are sent with every API request.

Refresh tokens are long-lived (days or weeks) and stored securely on the server side. When an access token expires, the client uses the refresh token to obtain a new access token without requiring the user to enter credentials again.

Client                    Server
  |                         |
  |-- Login (credentials) ->|
  |                         |-- Verify credentials
  |<-- Access + Refresh  ---|
  |                         |
  |-- API call + Access  -->|
  |                         |-- Verify token
  |<-- Response          ---|
  |                         |
  |-- Access expired     -->|
  |<-- 401 Unauthorized  ---|
  |                         |
  |-- Refresh token      -->|
  |                         |-- Verify refresh token
  |<-- New Access token  ---|

This pattern gives you the performance benefits of stateless JWTs (no database lookup on every request) with the security benefit of being able to revoke refresh tokens when needed.

Wrapping Up#

JWTs are a foundational technology for modern web authentication. They are compact, self-contained, and eliminate the need for server-side session storage. But they come with responsibilities — you need to choose the right algorithm, set proper expiration times, validate all claims, and never store sensitive data in the payload.

When you need to inspect or debug a token, use a JWT Decoder to instantly see its contents, verify its structure, and check its expiration status. Understanding what is inside your tokens is the first step toward building secure authentication systems.

This guide explains everything you need to know about JWTs. What they are, how they are structured, how to decode them, when to use them, and what security pitfalls to avoid.

What Is a JWT Token#

The Three Parts of a JWT#

Every JWT consists of three parts, separated by dots:

xxxxx.yyyyy.zzzzz

Here is a real example of what a JWT looks like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

That looks intimidating, but it is just three JSON objects encoded in Base64URL and concatenated with dots. Let us break each part down.

Part 1: The Header#

The header typically contains two fields: the signing algorithm (alg) and the token type (typ).

json

{
  "alg": "HS256",
  "typ": "JWT"
}

The header is Base64URL-encoded to produce the first part of the token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.

Part 2: The Payload#

The payload contains the claims — statements about the user and additional metadata. This is where the actual data lives.

json

{
  "sub": "1234567890",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516242622
}

Claims fall into three categories:

Registered claims are predefined by the JWT specification. They are not mandatory but are recommended for interoperability:

iss (issuer) — who created the token
sub (subject) — who the token is about (usually a user ID)
aud (audience) — who the token is intended for
exp (expiration time) — when the token expires (Unix timestamp)
nbf (not before) — the token is not valid before this time
iat (issued at) — when the token was created
jti (JWT ID) — a unique identifier for the token

Public claims are defined by the developer but should use collision-resistant names (often URIs) to avoid conflicts.

Private claims are custom claims agreed upon between parties, like role, permissions, or tenant_id.

Part 3: The Signature#

The signature is what makes JWTs trustworthy. It is created by taking the encoded header, the encoded payload, and a secret key, then applying the algorithm specified in the header.

For HMAC-SHA256, the signature is computed like this:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

How JWT Authentication Works in Practice#

Here is the typical flow when JWTs are used for authentication:

Step 1: The user sends their credentials (username and password) to the authentication endpoint.

Step 2: The server verifies the credentials. If valid, it creates a JWT containing the user's ID, roles, and an expiration time, then signs it with a secret key.

Step 3: The server sends the JWT back to the client.

Step 4: The client stores the token and includes it in the Authorization header of subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Step 5: For each request, the server extracts the token from the header, verifies the signature, checks the expiration time, and extracts the user's identity from the payload.

You can test this entire flow using an API Tester to see how authorization headers work with real endpoints.

How to Decode a JWT Token#

Decoding a JWT is straightforward because the payload is simply Base64URL-encoded, not encrypted. There are several ways to do it.

Using a Free Online Tool#

Using JavaScript#

javascript

function decodeJWT(token) {
  const parts = token.split(".");
  if (parts.length !== 3) {
    throw new Error("Invalid JWT format");
  }
 
  const header = JSON.parse(atob(parts[0].replace(/-/g, "+").replace(/_/g, "/")));
 
  const payload = JSON.parse(atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
 
  return { header, payload, signature: parts[2] };
}

Using Python#

python

import base64
import json
 
def decode_jwt(token):
    parts = token.split('.')
    # Add padding if needed
    payload = parts[1] + '=' * (4 - len(parts[1]) % 4)
    decoded = base64.urlsafe_b64decode(payload)
    return json.loads(decoded)

Using the Command Line#

bash

echo 'eyJzdWIiOiIxMjM0NTY3...' | \
  tr '_-' '/+' | \
  base64 -d 2>/dev/null | \
  python3 -m json.tool

Remember: decoding is not the same as verifying. Anyone can decode a JWT. Only someone with the secret key can verify that it is authentic.

Common JWT Use Cases#

API Authentication#

Single Sign-On (SSO)#

Microservice Communication#

Information Exchange#

Security Best Practices#

JWTs are powerful but can be dangerous if misused. Follow these practices to avoid common pitfalls.

Keep Tokens Short-Lived#

json

{
  "sub": "user123",
  "iat": 1711500000,
  "exp": 1711500900
}

That token expires after 15 minutes. If it is stolen, the window of exploitation is limited.

Never Store Sensitive Data in the Payload#

The payload is Base64URL-encoded, not encrypted. Anyone who intercepts the token can read its contents. Include only the minimum information needed — a user ID and role, not personal data.

Use Strong Signing Keys#

Always Validate the Signature#

Never skip signature verification. Some libraries have options to decode a token without verifying it — these should only be used for debugging, never in production.

Validate All Claims#

Check not just the signature but also the exp, iss, aud, and nbf claims. A valid signature on an expired token should still result in rejection.

Use HTTPS Everywhere#

JWTs transmitted over plain HTTP can be intercepted. Always use HTTPS in production. This is non-negotiable.

Choose the Right Algorithm#

Common JWT Vulnerabilities#

The `alg: none` Attack#

Algorithm Confusion#

Token Sidejacking#

Missing Expiration#

Excessive Payload Size#

JWT vs. Sessions: When to Use Which#

JWTs are not always the right choice. Here is a quick comparison:

Choose JWTs when:

You need stateless authentication at scale
You are building a distributed system or microservice architecture
You need cross-domain authentication (SSO)
Your API serves mobile clients, SPAs, or third-party consumers

Choose sessions when:

You need the ability to instantly revoke access (logout)
You are building a traditional server-rendered application
Your application is a monolith with a single server
You need to store large amounts of session data

Many production systems use a hybrid approach: JWTs for short-lived access tokens combined with server-side refresh token storage for revocation capability.

Token Expiration and Refresh Flow#

A well-designed JWT system uses two types of tokens:

Access tokens are short-lived (5 to 15 minutes) and contain the user's identity and permissions. They are sent with every API request.

Client                    Server
  |                         |
  |-- Login (credentials) ->|
  |                         |-- Verify credentials
  |<-- Access + Refresh  ---|
  |                         |
  |-- API call + Access  -->|
  |                         |-- Verify token
  |<-- Response          ---|
  |                         |
  |-- Access expired     -->|
  |<-- 401 Unauthorized  ---|
  |                         |
  |-- Refresh token      -->|
  |                         |-- Verify refresh token
  |<-- New Access token  ---|

This pattern gives you the performance benefits of stateless JWTs (no database lookup on every request) with the security benefit of being able to revoke refresh tokens when needed.

What Is a JWT Token#

The Three Parts of a JWT#

Part 1: The Header#

Part 2: The Payload#

Part 3: The Signature#

How JWT Authentication Works in Practice#

How to Decode a JWT Token#

Using a Free Online Tool#

Using JavaScript#

Using Python#

Using the Command Line#

Common JWT Use Cases#

API Authentication#

Single Sign-On (SSO)#

Microservice Communication#

Information Exchange#

Security Best Practices#

Keep Tokens Short-Lived#

Never Store Sensitive Data in the Payload#

Use Strong Signing Keys#

Always Validate the Signature#

Validate All Claims#

Use HTTPS Everywhere#

Choose the Right Algorithm#

Common JWT Vulnerabilities#

The alg: none Attack#

Algorithm Confusion#

Token Sidejacking#

Missing Expiration#

Excessive Payload Size#

JWT vs. Sessions: When to Use Which#

Token Expiration and Refresh Flow#

Wrapping Up#

İlgili Yazılar

Best Free Online Developer Tools Every Developer Needs in 2026

Free Base64, URL & HTML Encoder/Decoder Tools Online

What Is a JWT Token#

The Three Parts of a JWT#

Part 1: The Header#

Part 2: The Payload#

Part 3: The Signature#

How JWT Authentication Works in Practice#

How to Decode a JWT Token#

Using a Free Online Tool#

Using JavaScript#

Using Python#

Using the Command Line#

Common JWT Use Cases#

API Authentication#

Single Sign-On (SSO)#

Microservice Communication#

Information Exchange#

Security Best Practices#

Keep Tokens Short-Lived#

Never Store Sensitive Data in the Payload#

Use Strong Signing Keys#

Always Validate the Signature#

Validate All Claims#

Use HTTPS Everywhere#

Choose the Right Algorithm#

Common JWT Vulnerabilities#

The alg: none Attack#

Algorithm Confusion#

Token Sidejacking#

Missing Expiration#

Excessive Payload Size#

JWT vs. Sessions: When to Use Which#

Token Expiration and Refresh Flow#

Wrapping Up#

İlgili Yazılar

Best Free Online Developer Tools Every Developer Needs in 2026

Free Base64, URL & HTML Encoder/Decoder Tools Online

The `alg: none` Attack#

The `alg: none` Attack#