Developer

What's Inside a JWT? Header, Payload & Signature

Dev Nexus4 min read

A plain-English tour of a JWT's three parts and the standard claims you'll find in the payload.

A JSON Web Token is one long, dotted string — but it has a precise structure. Once you can see the three parts and know what the common claims mean, a JWT stops being an opaque blob and becomes something you can read and reason about.

This post breaks a token into its header, payload and signature, then walks through the registered claims you'll meet most often.

The Problem

Most developers first encounter JWTs as a mystery: a huge token appears in a header or cookie, and something, somewhere, decides whether the request is allowed. When it works, you don't think about it. When it breaks — a user is logged out early, an API returns undefined, a scope is missing — you need to know what the token actually contains, and the raw string tells you nothing.

Without a mental model of a JWT's anatomy, debugging is guesswork.

The Solution

A JWT has exactly three parts, separated by dots: header.payload.signature. The first two are BaseundefinedURL-encoded JSON — readable once decoded. The third is a cryptographic signature over the first two.

Decode a real token to see this in action. The JWT Decoder shows all three parts side by side, in your browser, without uploading anything. Because each segment is BaseundefinedURL-encoded, you can even decode one by hand with a Baseundefined tool — just remember it's the URL-safe variant, using - and _ instead of + and /.

Step-by-Step Guide

1
The header — how the token is signed
The first segment is a small JSON object describing the token itself. Its main fields are alg (the signing algorithm, e.g. HS256 or RS256) and typ (the type, almost always JWT). A verifier reads alg to know how to check the signature.
2
The payload — the claims
The second segment carries the claims: statements about the subject and the token. It's a JSON object of key-value pairs, mixing standard registered claims with any custom fields your application needs, such as scope, roles or email.
3
The registered claims worth knowing
Several claim names are standardized. sub is the subject (usually the user id). iss is the issuer, aud the intended audience. exp is the expiry time, iat the issued-at time, and nbf the not-before time — all Unix timestamps in seconds. jti is a unique token id.
4
The signature — proof of integrity
The third segment is created by signing the encoded header and payload with a secret (for HS256) or a private key (for RS256/ES256). It's raw bytes, not readable JSON. Its job is to let a server confirm the first two parts haven't been altered.

Common Mistakes

Believing the payload is encrypted
It isn't. The payload is only encoded, so anyone with the token can decode and read it. A standard JWT provides integrity (via the signature), not confidentiality. Never place secrets in the claims.
Confusing exp with a millisecond timestamp
The time-based claims — exp, iat and nbf — are all in Unix seconds. Treating them as milliseconds (as JavaScript's Date.now() returns) produces dates that are wildly wrong.
Ignoring nbf and aud
It's easy to check only exp. But a token can be rejected because the current time is before nbf, or because its aud doesn't match your service. When validation fails unexpectedly, read every claim, not just the expiry.
Assuming custom claims are standardized
Fields like roles, permissions or tenant are conventions, not part of the spec — their names and shapes vary by issuer. Don't assume another system's token uses the same custom claims yours does.

Frequently Asked Questions

How many parts does a JWT have?

Three: the header, the payload and the signature, joined by dots as header.payload.signature. The header and payload are Base64URL-encoded JSON; the signature is a cryptographic value.

What are registered claims?

Registered claims are standardized claim names defined by the JWT spec, such as sub, iss, aud, exp, iat, nbf and jti. Using them keeps tokens interoperable between different systems.

Are the header and payload encrypted?

No. They are Base64URL-encoded, which is reversible by anyone. A standard signed JWT protects integrity, not privacy, so anyone with the token can read its contents.

What's the difference between iat, nbf and exp?

iat is when the token was issued, nbf is the earliest time it's valid, and exp is when it expires. All three are Unix timestamps in seconds. A token is only valid between nbf and exp.