Robince Studio
Developer Tools

How JSON Web Tokens work, and how to read one safely

A JWT looks like a long random string, but it is three Base64URL-encoded pieces joined by dots, and two of them are plain JSON anyone can read. Understanding that clears up the most common security misunderstandings about tokens.

3 min read Reviewed Published by Abdul Gani, Robince Studio

On this page
  1. The three parts
  2. The payload is encoded, not encrypted
  3. What the signature protects
  4. Common claims
  5. Reading a token safely
  6. Mistakes developers make with JWTs
  7. Frequently asked questions
  8. Try these tools

The three parts

A JWT has the shape header.payload.signature. Each part is encoded with Base64URL, a variant of Base64 that is safe to put in URLs. Here is a small example with the signature left out:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFzaGEiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDAwMzYwMH0.<signature>

Decoding the first part gives {"alg":"HS256","typ":"JWT"}: the algorithm used to sign the token. Decoding the second gives the payload: {"sub":"1234567890","name":"Asha","iat":1700000000,"exp":1700003600}. The third part is the cryptographic signature and is not JSON.

The payload is encoded, not encrypted

This is the point people miss. Anyone who holds the token can decode and read the header and payload; no key is needed. Base64URL is just a way of writing bytes as text. Therefore a standard signed JWT must never contain secrets such as passwords, card numbers or private personal data.

There is a separate standard, JWE, which encrypts the contents, but it is much less common. If you see a three-part token, assume the payload is readable.

Signed does not mean secret. A signature proves the token was not changed. It does not hide what is inside.

What the signature protects

The server signs the header and payload with a secret key (HS256) or a private key (RS256, ES256). Later, when the token comes back, the server recomputes the signature. If someone changed even one character of the payload, the signature will not match and the token is rejected.

So the signature gives integrity and authenticity: the data came from the issuer and has not been altered. It is the verifying step on the server, not the decoding step, that makes a token trustworthy. Decoding alone proves nothing.

Common claims

ClaimMeaningExample
issWho issued the tokenhttps://auth.example.com
subThe subject, usually a user id1234567890
audWho the token is intended formy-api
expExpiry time as a Unix timestamp1700003600 = 2023-11-14 23:13:20 UTC
iatWhen it was issued1700000000 = 2023-11-14 22:13:20 UTC
nbfNot valid before this timea Unix timestamp

Reading a token safely

  • Decode tokens in a tool that runs in your browser and does not send them to a server. A live token is a credential until it expires.
  • Prefer using expired or test tokens when you share a token with someone or paste it into an issue tracker.
  • Check exp and iat as timestamps. The example token above lasted exactly one hour (3,600 seconds).
  • Remember that decoding a token tells you what it claims, not whether it is valid. Only the issuing server or a library with the right key can verify it.

Mistakes developers make with JWTs

  • Trusting a token without verifying its signature, or accepting the "none" algorithm.
  • Storing sensitive data in the payload.
  • Using very long expiry times. A stolen token works until it expires, so keep access tokens short-lived and refresh them.
  • Storing tokens where scripts can read them without considering cross-site scripting. Choose storage deliberately, for example an HTTP-only cookie.
  • Not planning for revocation. Because a JWT is self-contained, it stays valid until it expires unless the server keeps a deny list.

Frequently asked questions

Is a JWT encrypted?

A standard signed JWT is not encrypted. The payload can be read by anyone with the token. Only the signature stops it being modified without detection.

Can I trust the data in a decoded JWT?

Only after the signature has been verified with the correct key and the claims, such as expiry and audience, have been checked. Decoding by itself proves nothing.

How is Base64URL different from Base64?

Base64URL replaces + and / with - and _ and usually drops the = padding, so the result is safe to use in URLs and file names.

What does HS256 versus RS256 mean?

HS256 uses one shared secret to sign and verify. RS256 uses a private key to sign and a public key to verify, so many services can verify tokens without being able to create them.

Try these tools

Keep reading