JWT Decoder

What's inside a JWT

A signed JWT (a JWS, RFC 7515) has three parts, each Base64URL-encoded without padding, so the Base64 Decoder can read any one of them. That's encoding, not encryption: never put passwords, API keys or other secrets in a payload.

• Header: JSON naming the signing algorithm (alg), usually the type (typ: "JWT"), and often a key ID (kid) that tells the server which key to verify with.
• Payload: JSON with the claims, such as who the token is about, who it's for and when it expires.
• Signature: computed over header.payload with a shared secret or a private key.

Registered and OpenID Connect claims

RFC 7519 registers seven claims. All are optional, but most tokens carry several. The time claims are seconds since 1970-01-01 UTC, not milliseconds; the Unix Timestamp Converter converts one by hand.

• iss (issuer): who created the token, usually the login server's URL.
• sub (subject): the user or service the token is about.
• aud (audience): who the token is for. An API must reject tokens meant for another audience.
• exp (expiration time): don't accept the token at or after this time.
• nbf (not before): don't accept it before this time.
• iat (issued at): when the token was created.
• jti (JWT ID): a unique ID, used to stop the same token being replayed.
• ID tokens from OpenID Connect add azp, nonce, auth_time, at_hash, email, email_verified and name. Access tokens often carry scope or scp and roles.

HS256, RS256 and ES256

The alg header tells you how the token was signed:

• HS256: HMAC with SHA-256 and one shared secret, the same function the Hash Generator computes when you give it a key. The secret both signs and verifies, so any service that can check tokens can also create them.
• RS256: an RSA signature (RSASSA-PKCS1-v1_5) with SHA-256. The login server signs with its private key, and anyone can verify with the public key, often published as a JWKS at /.well-known/jwks.json.
• ES256: ECDSA with the P-256 curve and SHA-256. Same key model as RS256, with much shorter keys and signatures.

Why a token that decodes fine is still rejected

A clean decode only means the token is well formed. When an API still answers 401, compare the claims with what it checks:

• exp has passed. Libraries usually allow a minute or so of clock drift, but beyond that you need a new token, for example from the refresh token.
• nbf or iat is in the future. The clocks on the login server and the API disagree. Sync both with NTP, or allow a small leeway.
• aud doesn't match. A common case is sending the ID token to an API that expects an access token: the ID token's audience is your client app, not the API.
• iss doesn't match, for example a token from the staging login server sent to production, or an issuer URL with a trailing slash where the API expects none.
• The kid isn't in the issuer's JWKS. The signing keys were rotated and the API still has the old set cached, so it needs to fetch the JWKS again.
• The alg isn't on the API's list. That's the API doing its job: it should never let the token choose its own algorithm.

Decoding is not verification

Anyone can create a token with any claims, and this page would show it the same way. Trust a token only after your server has checked the signature with the right key and then checked exp, nbf, iss and aud. Use a maintained library for this.

Allow only the algorithms you expect. Libraries that trusted the token's own alg have been tricked into accepting alg: none, or into checking an RS256 token as HS256 with the public key used as the HMAC secret.

The last snippet only decodes, like this page. Use it for display or debugging, never to decide who gets access.

import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://login.example.com/.well-known/jwks.json"));
const { payload } = await jwtVerify(token, JWKS, {
  algorithms: ["RS256"],
  issuer: "https://login.example.com",
  audience: "api",
});

import jwt  # pip install PyJWT

payload = jwt.decode(
    token,
    secret,
    algorithms=["HS256"],
    audience="api",
    issuer="https://login.example.com",
)

keyFunc := func(t *jwt.Token) (any, error) { return []byte(secret), nil }
token, err := jwt.Parse(tokenString, keyFunc,
    jwt.WithValidMethods([]string{"HS256"}),
    jwt.WithIssuer("https://login.example.com"),
    jwt.WithAudience("api"),
)

const part = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
const payload = JSON.parse(
  new TextDecoder().decode(Uint8Array.from(atob(part), (c) => c.charCodeAt(0)))
);