How to Decode a JWT Token — and What the Three Parts Mean

What Is a JWT?

A JSON Web Token (JWT, pronounced "jot") is a compact, self-contained way to transmit claims between parties as a JSON object. It is widely used in authentication systems: after a user logs in, the server issues a JWT that the client includes in subsequent requests. The server can verify the JWT without maintaining session state — making JWTs popular in stateless REST APIs and microservice architectures.

A JWT looks like three base64url-encoded strings separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The three parts are: header . payload . signature

Part 1: The Header

The header is a base64url-encoded JSON object that describes the token's type and the signing algorithm. A typical header:

{"alg": "HS256", "typ": "JWT"}

• alg: The algorithm used to sign the token. HS256 means HMAC-SHA256 (a symmetric algorithm using a shared secret). RS256 means RSA-SHA256 (an asymmetric algorithm using a private key to sign, public key to verify).
• typ: Always JWT for JSON Web Tokens.
• kid: (Key ID) An optional identifier for which key was used to sign the token — useful when a server rotates keys.

Part 2: The Payload (Claims)

The payload is a base64url-encoded JSON object containing "claims" — statements about the subject of the token and additional metadata. RFC 7519 defines several standard registered claim names:

• sub (Subject): The principal the token is about — usually a user ID
• iss (Issuer): Who issued the token — usually the authentication server URL
• aud (Audience): Who the token is intended for — usually the API or service that will consume it
• exp (Expiration Time): Unix timestamp after which the token must not be accepted
• iat (Issued At): Unix timestamp when the token was issued
• nbf (Not Before): Unix timestamp before which the token must not be accepted
• jti (JWT ID): A unique identifier for this specific token, used to prevent replay attacks

Beyond these standard claims, any additional key-value pairs are "private claims" and can contain anything the application needs: user roles, permissions, plan level, or custom identifiers.

Part 3: The Signature

The signature is computed by taking the base64url-encoded header and payload, joining them with a dot, and passing the result through the signing algorithm:

HMAC-SHA256(base64url(header) + "." + base64url(payload), secret)

The signature proves two things: that the token was issued by someone who possesses the secret key, and that the header and payload have not been modified since signing. If any bit of the header or payload changes, the signature verification fails.

What Client-Side Decoding Can and Cannot Verify

Decoding a JWT without the secret key can read the header and payload claims — including user ID, expiry, and permissions — but cannot verify the signature. This is useful for inspection and debugging, but the decoded values should never be trusted for access control without server-side verification.

A properly secured API verifies the JWT signature on every request before acting on its claims. Client-side decoding is only for display purposes — showing the user their username, expiry time, or role.

The alg:none Vulnerability

Some early JWT libraries had a critical flaw: they accepted tokens with "alg": "none" in the header, meaning no signature was required. An attacker could forge any token by setting the algorithm to "none" and omitting the signature. All modern JWT libraries should explicitly reject alg:none and only accept the specific algorithms configured by the application.

JWT vs Session Cookies

JWTs are stateless — the server does not need to store session data. This simplifies horizontal scaling (any server can verify any JWT) but makes token revocation difficult. A session cookie can be invalidated server-side immediately; a JWT remains valid until its exp claim, even if the user logs out. Applications needing immediate revocation must maintain a token blocklist — partially negating the statelessness advantage.