
Decode JWT: How to Decode a JSON Web Token Safely (With Examples)
To decode JWT means to take a JSON Web Token — the long string of characters separated by dots that you see in an Authorization header — and read the information inside it. Decoding is easy, because a JWT is not encrypted. That is also why it is dangerous to misunderstand: anyone who has a token can decode it, so a JWT must never contain a password, a secret or anything else you would not show to the user it belongs to.
This guide explains what a JWT is, how to decode it step by step — in a browser tool, on the command line and in code — how to read the claims inside it, and, most importantly, why decoding is not the same as trusting it.

What Is a JWT?
A JSON Web Token (JWT) is a compact, URL-safe way to pass claims between two parties. It is defined in RFC 7519 and is used most often for authentication: after you log in, a server gives you a JWT, and you send it back with each request to prove who you are. The server reads the token, checks that it is genuine, and lets you in — without looking up a session in a database every time.
A JWT has three parts, separated by dots:
header.payload.signature
Each part is encoded in base64url, a variant of base64 that is safe to put in a URL. The header says how the token is signed. The payload, also called the claims, says who the token is for and what it allows. The signature proves the token has not been changed since it was issued.
| Part | What It Contains | Example |
|---|---|---|
| Header | Token type and signing algorithm | {"alg":"HS256","typ":"JWT"} |
| Payload | Claims: subject, issuer, expiry and custom data | {"sub":"1234567890","name":"John Doe","iat":1516239022} |
| Signature | A hash of header + payload, made with a secret or private key | SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c |
Worked Example: Decode a JWT by Hand
Take the example token from the JWT standard’s own documentation. It is a demo token, not a real credential, and it is the token shown on jwt.io:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Split it on the dots. There are three parts:
- Header:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9— decode the base64url and you get{"alg":"HS256","typ":"JWT"}. The token is signed with HMAC-SHA256. - Payload:
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ— decoded, that is{"sub":"1234567890","name":"John Doe","iat":1516239022}. The subject is user 1234567890, the name is John Doe, and the token was issued at Unix time 1516239022, which is 18 January 2018. - Signature:
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c— this is not readable data. It is the output of signing the first two parts with a secret key, and it is what a server checks before trusting the token.
Notice what decoding did not do: it did not prove the token is genuine. Anyone can create a token that decodes to the same header and payload. The signature is the only part that proves the token was issued by someone who holds the secret.
How to Decode JWT Tokens: 4 Methods
1. Use an online JWT decoder (fastest)
Paste the token into a decoder such as jwt.io, jwt.ms or an online JWT decoder tool. The site splits the token, decodes the header and payload, and shows them as readable JSON. It will also warn you if the token is malformed or expired. Only use this method with test or demo tokens — never paste a real production token into a third-party website, because the site then has your credentials.
2. Use the command line
On Linux or macOS, you can decode the payload without installing anything, using the token’s second part:
echo 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ' | base64 -d
Base64url uses - and _ where standard base64 uses + and /, and it omits padding, so for a real token you may need to replace those characters and add = padding first. Many developers use jq to format the result as readable JSON.
3. Decode a JWT in JavaScript
const token = 'eyJhbGciOi...';
const payload = JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
console.log(payload);
This is useful for debugging in a browser console. It decodes the token; it does not verify it. Libraries such as jsonwebtoken (Node.js) and PyJWT (Python) provide a decode function for the same purpose, and a separate verify function for checking the signature.
4. Decode a JWT in Python
import base64, json
part = 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ'
part += '=' * (-len(part) % 4)
print(json.loads(base64.urlsafe_b64decode(part)))
The padding line is needed because base64url tokens omit the = characters that Python’s decoder expects.
Reading JWT Claims: The Fields That Matter
| Claim | Meaning | What to Check |
|---|---|---|
iss |
Issuer — who created the token | Is it the identity provider you expect? |
sub |
Subject — who the token is about | Does it match the user making the request? |
aud |
Audience — who the token is for | Is it intended for your application? |
exp |
Expiry time (Unix seconds) | Has it passed? Reject expired tokens. |
nbf |
Not before — earliest valid time | Is it too early to accept? |
iat |
Issued at | Is it implausibly old or in the future? |
jti |
JWT ID — a unique identifier | Use it to revoke or track a specific token. |
Custom claims can also appear, such as a user’s role or permissions. Treat those with the same suspicion as the standard claims: they are only as trustworthy as the signature that protects them.
Decode JWT vs Verify JWT: The Difference That Matters
Decoding reads a token. Verifying checks it. A server that only decodes a token will accept a forged one, because decoding does not check the signature, the issuer, the audience or the expiry time.
| Step | Decode | Verify |
|---|---|---|
| Reads header and payload | Yes | Yes |
| Checks the signature | No | Yes, with the secret or public key |
Checks expiry (exp) |
No | Yes |
| Checks issuer and audience | No | Yes |
| Safe to trust the claims | No | Yes, if all checks pass |
That is why libraries have two functions, and why the verify function is the one your application should call. Use decode only for debugging, logging and displaying information — never to decide whether a user is allowed in.
Security Mistakes to Avoid When You Decode JWT
- Trusting a decoded token. A decoded payload is a claim, not a fact. Always verify the signature first.
- Accepting
alg: none. Some libraries used to accept tokens with no signature at all. Reject any token whose algorithm isnone, and only accept the algorithms you expect. - Putting sensitive data in the payload. The payload is base64, not encrypted. Anyone who has the token can read it. Store only an identifier, and look up the sensitive data server-side.
- Pasting real tokens into online decoders. A production token is a credential. Paste it into a website and you have shared it with that website. Use a local decoder or a test token instead.
- Ignoring expiry. A token without an
expclaim, or with a very long lifetime, is a credential that cannot be revoked easily. Keep lifetimes short — minutes to hours, not days — and use refresh tokens for longer sessions. - Storing tokens where scripts can read them. A token in local storage can be stolen by cross-site scripting. Prefer httpOnly cookies for browser sessions, and keep tokens out of URLs, where they end up in logs.
Weak passwords make token theft far more damaging, because an attacker who guesses a password gets a valid token. That is why the most common passwords are still a serious risk, and why authentication should use more than a password alone — see our guide to the RADIUS protocol for how network authentication works in practice.
Frequently Asked Questions
How do I decode a JWT online?
Paste the token into a decoder such as jwt.io or jwt.ms. It will split the token into header, payload and signature and show the first two as readable JSON. Use test tokens only, not production credentials.
Can I decode a JWT without the secret?
Yes. Decoding only needs the token itself, because the header and payload are base64url-encoded, not encrypted. You need the secret or public key only to verify the signature.
Is a JWT encrypted?
No, a standard JWT (a JWS) is signed, not encrypted. Anyone can decode and read it. Encrypted JWTs exist — they are called JWEs — but they are a different format and are much less common.
Why does my JWT decode fail?
Common causes are a token that has been truncated when copied, extra whitespace or quotation marks, a payload that is not valid base64url, or a token that is not a JWT at all — for example, an opaque session token. Check that the token has exactly two dots and three parts.
How do I check if a JWT is expired?
Decode the payload and read the exp claim, which is a Unix timestamp in seconds. If the current time is after exp, the token is expired. For example, exp: 1516239022 is 18 January 2018, so a token with that expiry is long expired. Access control should also check the token’s audience and issuer — see network access control for the wider picture.
Conclusion
Decoding a JWT is simple: split it on the dots, base64url-decode the header and payload, and read the JSON. The hard part is remembering what decoding does not do. It does not prove the token is genuine, it does not check expiry, and it does not make the contents private. Decode to debug, verify to trust — and never put a secret in a token.


