How JSON Web Tokens (JWT) Work — and What They Do Not Do

JSON Web Tokens are a compact way to pass claims between parties. They are used for authentication, single sign-on and API authorization. Despite their popularity, JWTs are frequently misunderstood — especially the difference between decoding and verifying.

The three parts of a JWT

A JWT is a string with three segments separated by dots: header, payload and signature.

• The header describes the token type and signing algorithm.
• The payload holds the claims, such as user ID and expiry.
• The signature lets a trusted party confirm the token was not tampered with.

The first two segments are simply Base64URL-encoded JSON and can be decoded by anyone.

Decoding is not verification

Decoding a JWT only reveals its contents. It does not prove the token is authentic. Never accept a token as trusted unless its signature is verified with the correct key or secret, and the issuer, audience and expiry are checked.

Decoding the payload

JavaScript:

const [, payload] = token.split('.')
const json = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')))

Python:

import base64, json
payload = token.split('.')[1]
padding = '=' * (-len(payload) % 4)
print(json.loads(base64.urlsafe_b64decode(payload + padding)))

PHP:

[$header, $payload, $sig] = explode('.', $token);
echo base64_decode(strtr($payload, '-_', '+/'));

Common pitfalls

• Storing secrets in the payload, where they are readable by anyone.
• Forgetting to verify the signature before trusting claims.
• Ignoring the exp expiry or aud audience claim.

Frequently asked questions

• Can anyone read a JWT? Yes. The header and payload are only encoded, not encrypted.
• Does decoding prove the token is valid? No. Validity requires signature and claim verification.
• Is my token uploaded when I inspect it? No. Decoding can happen entirely in your browser.

Need to inspect a JWT quickly and privately? Use the free JWT Decoder — it decodes the header and payload locally without sending anything anywhere.