JWT decoder and verifier

A signed JWT is three base64url segments joined by dots: a header, a payload and a signature. The header is JSON naming the algorithm in alg and often a type in typ and a key ID in kid. The payload, which RFC 7519 calls the claims set, is a JSON object of claims such as sub, aud and exp. The signature is computed over the exact ASCII text of the first two segments and the dot between them, so changing a single character of either breaks it.

Base64url is the URL-safe form of base64: "-" and "_" replace "+" and "/", and the "=" padding is dropped (RFC 7515). Every header starts with "eyJ", which is simply the encoding of {", and that is a quick way to recognise a JWT in a log or a request.

An encrypted token, a JWE under RFC 7516, has five segments instead: a protected header, an encrypted key, an initialisation vector, the ciphertext and an authentication tag. Only its header can be read without the decryption key.

The header and payload of a signed JWT are encoded, not encrypted. Anyone holding the token can read them, exactly as this page does, without any key. That is why a JWT must never carry a password, an API key or personal data its holder should not see.

Decoding also proves nothing about who made the token. Anyone can write a header and payload and encode them. Only verifying the signature with the right key shows that the issuer created it and that nobody has changed it since. A frequent bug is code that calls a library's decode function, which skips verification, where it should call verify.

A full validation checks, in order: the algorithm is one the API expects, the signature verifies with a trusted key, the token has not expired and is already valid, the issuer is trusted, and the audience names this API. A test suite should prove each of those checks on its own.

RFC 7519 registers seven claims, all optional in the standard, which makes it the API's job to require the ones it relies on. In access tokens, exp, iss and aud should be mandatory, and sub identifies the user or client the API acts for.

RFC 8725, the JWT best current practice, lists the attacks that have broken real systems. Each maps to a negative test you can run against your own API, and the tool above generates the tokens for most of them.

Servers' clocks drift, so RFC 7519 allows a small leeway, usually no more than a few minutes, when checking exp and nbf. That leeway is a boundary worth testing. With a 60-second allowance, a token that expired 30 seconds ago should be accepted and one that expired 90 seconds ago rejected. Find the configured value, then test just inside and just outside it.

Test the moment of expiry itself: the token must be rejected at exp, not one second after. Check a token with nbf in the future, a token with no exp at all, and one whose exp is a string. And check what the client does when its token expires mid-session: it should refresh once and retry, not loop or log the user out.

To test these checks independently of the signature check, the expired or changed token must carry a valid signature. Enter a test environment secret or private key in the tool above and the negative test tokens are re-signed in your browser.

A JWT is a bearer credential: whoever holds it can use it until it expires. Pasting a live production token into a website that logs requests gives that site your session. This page decodes, verifies and signs entirely in your browser with Web Crypto and sends nothing to any server, but the safer habit is still to use tokens from test environments.

In defect reports, include the decoded header and claims rather than the token. The Markdown export leaves the signature out for that reason. Logs deserve the same care: an application that writes full Authorization headers to its logs turns every log reader into a potential user of every account.