How to Decode a JWT Token (Step by Step)

What Is a JWT?

A JSON Web Token (JWT) is a compact, URL-safe token format used to securely transmit information between two parties. JWTs are widely used for authentication (proving who you are) and authorization (proving what you can access) in modern web applications.

A JWT looks like three Base64url-encoded strings separated by dots:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NSJ9.abc123signature

The Three Parts of a JWT

1. Header

The header is a JSON object that specifies the token type (usually "JWT") and the signing algorithm (e.g., HS256, RS256). When decoded:

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

2. Payload (Claims)

The payload contains the claims — statements about the user and additional metadata. Common registered claims include:

• sub (subject) — the user ID
• iat (issued at) — when the token was created (Unix timestamp)
• exp (expiration) — when the token expires
• iss (issuer) — who issued the token
• aud (audience) — the intended recipient

You can also include custom claims like "role": "admin" or "plan": "pro".

3. Signature

The signature is created by taking the encoded header and payload, concatenating them with a dot, and signing the result with a secret key (HMAC) or a private key (RSA/ECDSA). This ensures the token has not been tampered with.

How to Decode a JWT Step by Step

1. Copy the token from your browser's developer tools, API response, or authorization header.
2. Split at the dots to isolate the three parts: header, payload, and signature.
3. Base64url-decode the header and payload to see the raw JSON.
4. Inspect the claims — check the expiration, subject, issuer, and any custom fields.
5. Verify the signature (optional) — if you have the secret or public key, you can confirm the token is authentic and unmodified.

Important Security Notes

• Decoding is not verification. Anyone can decode a JWT — the payload is not encrypted. Only signature verification proves the token is legitimate.
• Never store secrets in the payload. Treat claims as public information. Use encryption (JWE) if you need to hide data.
• Always validate expiration. Check the exp claim server-side to reject expired tokens.
• Use strong algorithms. Prefer RS256 or ES256 over HS256 in production to avoid shared-secret vulnerabilities.
• Watch for the "none" algorithm attack. Your server should reject tokens with "alg": "none".

Common JWT Debugging Scenarios

"My API returns 401 Unauthorized" — decode the token and check if exp is in the past. Expired tokens are the number one cause of unexpected 401 errors.

"My token works locally but not in production" — compare the iss and aud claims. Different environments often use different issuers or audiences.

"I need to see what permissions the user has" — decode the payload and look for role or scope claims like "scope": "read write".

Conclusion

Decoding JWTs is a daily task for backend and frontend developers alike. Understanding the three-part structure helps you debug authentication flows, verify token contents, and catch security misconfigurations early. Bookmark our JWT Decoder for instant token inspection.