SpunkArt
Data, text and encoding

Reading a JSON Web Token

A JSON Web Token, or JWT, is three base64url strings joined by dots. Anyone holding a token can decode the first two parts and read them. Only a server with the right key can check the third part, and that check is the only thing that makes a token trustworthy.

Decode a JWT (no verification)

The sample token above is a demo we built for this page. It was signed with HS256 and the throwaway key example-secret-not-for-real-use, and it expired long ago. Do not paste a live production token into any website, including this one; decode real tokens in your own terminal.

The three parts

header . payload . signature
  1. Header – JSON that names the signing algorithm. The sample decodes to {"alg":"HS256","typ":"JWT"}.
  2. Payload – JSON with the claims: statements about the user and the token itself.
  3. Signature – bytes computed from the first two parts and a key. It is not JSON and does not decode to anything readable.

Each part uses base64url: the URL-safe Base64 alphabet with - and _, and no = padding. That is why almost every JWT starts with eyJ: it is the encoding of {".

Decoding by hand

You need no special tool. In a terminal:

echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' | base64 -d
{"alg":"HS256","typ":"JWT"}

The payload may need padding first. Its length must be a multiple of 4, so add one or two = signs, and swap - for + and _ for / if they appear. The sample payload decodes to:

{"sub":"demo-user-42","name":"Example Person","role":"reader",
 "iat":1700000000,"exp":1700003600}

Reading the claims

ClaimMeaningIn the sample
subSubject: who the token is aboutdemo-user-42
iatIssued at, in Unix seconds1700000000 = 2023-11-14 22:13:20 UTC
expExpiry, in Unix seconds1700003600 = 2023-11-14 23:13:20 UTC
nbfNot valid before this time(not set)
iss, audIssuer and intended audience(not set)

Lifetime check: exp − iat = 1700003600 − 1700000000 = 3,600 seconds, so the sample was valid for exactly one hour. The timestamp guide explains the seconds-since-1970 format.

Decoding is not verifying

Anyone can change "role":"reader" to "role":"admin", re-encode the payload, and paste the old signature on the end. A decoder will happily show the forged claims. Only verification catches it: the server recomputes the signature over the header and payload with its key and compares. With HS256 that is an HMAC-SHA256 using a shared secret; with RS256 or ES256 the server checks a signature against a public key.

A correct verifier also:

  • accepts only the algorithms it expects, and never "alg":"none";
  • rejects tokens past exp or before nbf, allowing a small clock skew;
  • checks iss and aud so a token minted for another service is refused.

Common mistakes

  • Putting secrets in the payload. It is encoded, not encrypted. Assume every claim is public.
  • Trusting a decoded token in the browser. Front-end code may read claims to show a name, but every access decision belongs on the server after verification.
  • Reading exp as milliseconds. JWT times are seconds. Multiply by 1,000 before passing them to JavaScript’s Date.

Questions

Can this page verify a signature?

No, by design. Verifying needs the key, and a secret key should never be typed into a web page. The tool only decodes and labels the signature as unverified.

Can I log a user out by deleting their JWT?

Deleting it on the client stops that browser from sending it, but a copy stays valid until exp. That is why access tokens are kept short-lived.