You are debugging an authentication issue. The API is returning a 401, and you suspect the token payload has the wrong role claim. Your first instinct is to Google "JWT decoder", paste the token into the first result, and read the payload.
That token is your active session credential. You just handed it to a stranger's server.
This guide explains exactly what is inside a JSON Web Token, how decoding works, and why a local browser-based decoder is not just more convenient — it is the only secure option.
The Three Parts of Every JWT
Every JWT consists of three Base64URL-encoded sections separated by dots:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwicm9sZSI6ImFkbWluIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Part 1 (Header): eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Part 2 (Payload): eyJzdWIiOiIxMjM0NTY3ODkwIi...
Part 3 (Signature): SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Part 1: The Header
The header declares the token type and the signing algorithm. Decoded, it looks like this:
{
"alg": "HS256",
"typ": "JWT"
}
The alg field tells the server which algorithm was used to create the signature. Common values include HS256 (HMAC-SHA256), RS256 (RSA), and ES256 (Elliptic Curve). This field is critical — certain older JWT libraries trusted the alg field in the token itself, which led to the infamous "alg:none" vulnerability where attackers stripped the signature entirely.
Part 2: The Payload
The payload contains the claims — the actual data the token carries. A typical payload looks like:
{
"sub": "1234567890",
"name": "John Doe",
"role": "admin",
"iat": 1716239022,
"exp": 1716242622
}
Key standard claims include sub (subject, usually a user ID), iat (issued at, Unix timestamp), exp (expiration, Unix timestamp), and aud (audience, which service this token targets). Custom claims like role, permissions, or tenant_id are added by your application and are the claims you most often need to inspect when debugging.
Part 3: The Signature
The signature is created by the server using a secret key and cannot be forged without that key. It guarantees the token has not been tampered with. Importantly, the signature does not encrypt the payload — anyone who holds the token can read the header and payload. Only the server can verify the signature.
This is the most misunderstood aspect of JWTs: they are not secret by default. They are signed, not encrypted.
Why Decoding Requires Only Base64
Since the header and payload are simply Base64URL-encoded, decoding requires no cryptographic key whatsoever:
// This is all a JWT decoder does:
function decodeJWT(token) {
const parts = token.split('.');
const header = JSON.parse(atob(parts[0].replace(/-/g, '+').replace(/_/g, '/')));
const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
// The signature cannot be verified without the server's secret key
// But header and payload are fully readable without any key
return { header, payload };
// Zero network requests. Zero server needed.
}
This runs entirely in your browser. There is absolutely no technical reason any decoder tool needs to send your token to a server.
The Catastrophic Risk of Cloud JWT Decoders
A JWT is not just data — it is an active credential. If your token contains a valid, unexpired session, anyone who possesses it can authenticate as you.
When you paste a JWT into a cloud decoder:
1. Your token is sent via HTTPS to their server
2. Their server logs the request (standard web server behaviour)
3. The log entry contains: your IP + timestamp + your full JWT
4. If that log is ever exposed in a breach:
→ Attacker reads your token
→ If not yet expired, they authenticate as you
→ They access whatever your role permits — including admin functions
For short-lived tokens (15-minute expiry), the risk window is small. However, for tokens with 24-hour or 7-day expiry — common in production applications — a leaked token from a debug session could still be active long after.
Additionally, if the payload contains user PII (name, email, user ID), you are transmitting personal data to an unvetted third party — a GDPR and SOC2 compliance violation.
How to Decode Locally
SolveBar's JWT Decoder runs the exact same atob() logic shown above, entirely in your browser. Paste your token, and the header and payload render instantly. Open your browser's Network tab — you will see zero POST requests. Your token exists only in your local tab memory and vanishes when you close it.
The tool also highlights expiry status, flags common security misconfigurations like alg:none, and formats the JSON payload for easy reading — all without a single byte leaving your machine.
What to Inspect When Debugging
When a JWT-related auth issue appears, check these fields first:
exp claim: Convert the Unix timestamp to a readable date. A token that expired two hours ago explains a 401 immediately.
aud claim: If present, the token is only valid for a specific service. Sending a token intended for api.example.com to admin.example.com will be rejected.
alg field: If this is none or missing, your server has a critical misconfiguration.
Custom role claims: Verify the role or permission claims match what the endpoint requires. A user with role: "viewer" calling an admin endpoint explains a 403.
FAQ
Can anyone read my JWT payload without a key?
Yes. The payload is Base64URL-encoded, not encrypted. Anyone who holds the token can decode and read the claims. If you need the payload to be confidential, use JWE (JSON Web Encryption) instead of standard JWT.
Is a JWT the same as a session cookie?
No. A session cookie stores only a session ID; the actual data lives on the server. A JWT is self-contained — the server validates it cryptographically without a database lookup. This makes JWTs stateless but means they cannot be invalidated before expiry.
Why do cloud JWT decoders need my token at all?
They do not. Decoding is purely a Base64 operation that runs natively in any browser. Any tool that sends your token to a backend has no technical justification for doing so.
What happens if my JWT is stolen?
The attacker can authenticate as you until the token expires. Unlike passwords, you cannot change a JWT — you must wait for expiry or implement server-side token revocation.
How do I check if a JWT decoder is truly local?
Open browser DevTools, go to the Network tab, clear it, then paste your token. If any outbound POST or GET requests appear, the tool is sending your data externally. SolveBar's decoder produces zero network activity.
Decode your JWTs privately with the SolveBar JWT Decoder — no server, no logs, no risk to your active sessions.