How to decode a JWT and read its claims

JSON Web Tokens, or JWTs, carry login sessions and API permissions in countless applications. When something goes wrong, such as a user being logged out too early or an API refusing a request, the first step is often to look inside the token. That is easy, because a standard JWT is encoded, not encrypted.

The three parts

A JWT looks like eyJhbGciOi….eyJzdWIiOi….SflKxwRJ…: three sections separated by dots.

1. Header: the token type and signing algorithm, such as HS256 or RS256.
2. Payload: the claims: who the token is for, who issued it, when it expires, and any custom data.
3. Signature: proof that the header and payload have not been changed, created with a secret or private key.

The header and payload are JSON, encoded with Base64URL, a web-safe variant of Base64 without padding.

Decode it step by step

1. Copy the token and split it at the dots.
2. Paste the second part, the payload, into the Base64 Decoder. It handles the URL-safe alphabet and missing padding automatically.
3. Read the JSON, or paste it into the JSON Formatter to make it easier to scan.
4. Do the same with the first part to see the header.

The decoding happens in your browser. That matters: a live token is a key to an account, and pasting it into a website that sends it to a server is a real risk.

Common claims

• iss: issuer, the service that created the token.
• sub: subject, usually the user ID.
• aud: audience, which service the token is meant for.
• exp: expiry time, as a Unix timestamp in seconds.
• iat and nbf: issued at, and not valid before.

To read the times, paste exp or iat into the Timestamp Converter. A token that expires a few minutes after it was issued explains sudden logouts; a token whose nbf is in the future suggests a clock problem on one of the servers.

Decoding is not verifying

Anyone can decode a JWT, and anyone can create one with any claims they like. What makes a token trustworthy is the signature, checked with the right key by the server. Never make security decisions in client code based on decoded claims alone, and never trust a token whose header says "alg": "none". Verification belongs in the server, using a well-maintained library.

Do not put secrets in a JWT

Because the payload is readable by anyone who holds the token, it should never contain passwords, personal data beyond what is necessary, or internal secrets. If the contents must be hidden, the token needs to be encrypted (a JWE, which has five parts rather than three), not just signed.

Handle real tokens with care

• Prefer a token from a test account when debugging.
• Do not paste tokens into chat, tickets or logs.
• If a production token has been exposed, revoke it or rotate the signing key.

For the encoding itself, see what Base64 is. For timestamps, see Unix timestamps explained.