JWT Decoder and Verifier

What a JWT decoder does

A JWT (JSON Web Token, RFC 7519) is three base64url strings joined by dots: a header naming the signing algorithm, a payload of claims such as sub and exp, and a signature over the first two. Decoding only reverses the base64url, so anyone holding a token can read every claim in it; verifying checks the signature with the issuer's secret or public key, and only a verified token proves who issued it and that nobody changed it.

That difference is where most JWT bugs live. In the Node.js jsonwebtoken package, jwt.decode() checks nothing, while jwt.verify() checks the signature and the expiry. An API that reads claims from a decoded but unverified token trusts whatever the caller wrote.

How the decoder works

The token is split on its dots, each part is base64url-decoded strictly (a +, / or stray character is reported with its position), and the header and payload must be UTF-8 JSON objects. The signature is checked with the browser's WebCrypto, with the algorithm taken from the header and the key you supply. A five-part token is an encrypted JWE: its header is readable, its payload is not without the recipient's private key.

The signing algorithms

The key can be pasted as a PEM public key, a PKCS#1 RSA PUBLIC KEY, an X.509 certificate, a single JWK, or a whole JWKS such as the one an identity provider publishes at /.well-known/jwks.json; with a JWKS the key whose kid matches the token's header is used.

Claims and clock skew

exp (expiry), nbf (not before) and iat (issued at) are NumericDate values: seconds since 1970, not milliseconds. The decoder shows each as a UTC time and relative to now, and applies a clock-skew allowance (60 seconds by default) the way verification libraries do, because two servers' clocks are never exactly equal. iss and aud say who issued the token and who it is for; a verifier should check both.

Worked example: verify on the command line

Decode a payload with standard tools (base64url needs its alphabet swapped and its padding restored first):

b64url() { s=$(tr '_-' '/+'); while [ $(( ${#s} % 4 )) -ne 0 ]; do s="$s="; done; printf '%s' "$s" | base64 -d; }
TOKEN='eyJhbGciOi...'
printf '%s' "$TOKEN" | cut -d. -f2 | b64url; echo

Check an RS256 signature with OpenSSL and the issuer's public key:

printf '%s' "$TOKEN" | cut -d. -f1,2 | tr -d '\n' > signed.txt
printf '%s' "$TOKEN" | cut -d. -f3 | b64url > signature.bin
openssl dgst -sha256 -verify public.pem -signature signature.bin signed.txt

Verified OK means the token is genuine. ES256 signatures need converting to DER before openssl dgst accepts them, which is one reason a browser check is handier.

Common errors and how to fix them

• invalid signature: the secret or key is wrong. Check whether the secret is meant to be base64-decoded first, whether the issuer rotated its keys (the kid will not be in the JWKS you have), and whether the token was copied whole.
• jwt expired: exp has passed. Refresh the token; if it happens only on one server, compare clocks with timedatectl and enable NTP.
• jwt malformed: not three parts. Quotes, a Bearer prefix or line breaks from copying are the usual cause.
• invalid algorithm: the token's alg is not one the server allows. Good: pin the expected algorithm, so an attacker cannot switch RS256 to HS256 and sign with your public key as the secret.
• ES256 signature fails everywhere: the signer wrote a DER signature (usually 70 to 72 bytes) instead of the 64-byte raw form JWS requires.

A short security checklist

RFC 8725 collects the lessons: pin the algorithms you accept and refuse none; check exp, nbf, iss and aud; never fetch a key from a jku or x5u URL the token itself supplies; keep access tokens short-lived; and never put secrets in the payload, which anyone can read.

JWT secrets and Shipown

When you deploy a Node.js API with Shipown, its JWT signing secret belongs in the app's environment values, not in the repository; they are sent to the build or deployment machine as needed, as the credentials page explains. To decode the base64 parts by hand, use the base64 decoder.