What Is a JWT?

The short version

A JSON Web Token, or JWT, is a compact, URL-safe string that carries information, called claims, between two parties. The token is signed, so the receiver can check that it was issued by someone with the right key and has not been changed. JWTs are described in RFC 7519.

Structure

A JWT has three parts, separated by dots:

header.payload.signature

• Header: JSON describing the token and the signing algorithm.
• Payload: JSON holding the claims.
• Signature: proof that the first two parts came from the key holder and were not altered.

Each of the first two parts is Base64URL encoded. The signature is computed over the encoded header, a dot and the encoded payload.

Registered claims

The standard names are iss (issuer), sub (subject), aud (audience), exp (expiry), nbf (not before), iat (issued at) and jti (token ID). Times are Unix timestamps in seconds.

Signing algorithms

HMAC algorithms such as HS256 use one shared secret to sign and verify. RSA and ECDSA algorithms such as RS256 and ES256 use a private key to sign and a public key to verify, so receivers never hold the signing key.

Signed, not encrypted

The payload is only encoded, not hidden. Anyone with the token can read it. Never put passwords or private data in a JWT. If you need confidentiality, use an encrypted form or keep the data on the server.

Using JWTs safely

• Always verify the signature, and check exp, iss and aud.
• Allow only the algorithms you expect, and reject none.
• Use long random secrets, at least 32 bytes for HS256.
• Keep lifetimes short and send tokens only over HTTPS.
• Plan how you will revoke or rotate keys, for example with the kid header.

In code

// Node.js with the jsonwebtoken library
const token = jwt.sign({ sub: "123" }, secret, { expiresIn: "1h" });

# Python with PyJWT
token = jwt.encode({"sub": "123"}, secret, algorithm="HS256")

Try it

Build a token with the JWT encoder, set times in the claims builder, or shape the header with the header builder.