Skip to content
Velloreth
Cybersecurity 5 min read

JWT Explained: Structure, Signing and Pitfalls

A JWT is three base64url parts joined by dots. Learn how signing works, what it proves, and the mistakes that make tokens insecure.

By

What a JWT is

A JSON Web Token is a compact, URL-safe string that carries a set of claims and a signature. It is defined by RFC 7519, and it is used most often as an access token or an ID token in an OAuth or OpenID Connect flow.

The value of a JWT is that it is self-contained. A server can verify the signature with a key it already has, read the claims, and make an authorisation decision without a database lookup. That is the whole point, and it is also the source of its main limitation.

The three parts

A JWT is three base64url-encoded parts joined by dots.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The header describes the token. It names the signing algorithm and the type.

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

The payload carries the claims. The registered claims are iss (issuer), sub (subject), aud (audience), exp (expiry), nbf (not before), iat (issued at), and jti (JWT ID). Any other claim is application-defined.

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622
}

The signature is computed over the first two parts. For HS256 it is an HMAC with a shared secret; for RS256 it is an RSA signature with a private key.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

The payload is not secret

This is the mistake that causes the most damage. The payload is base64url-encoded, which is a reversible encoding, not encryption. Anyone who holds the token can read every claim in it.

# Decode the payload without any key
echo "eyJzdWIiOiIxMjM0NTY3ODkwIn0" | base64 -d
# {"sub":"1234567890"}

Never put a secret in a JWT payload. No passwords, no API keys, no personal data that should not be visible to the holder. The signature proves the content is authentic; it does not hide it.

Signing algorithms

HS256 is HMAC with SHA-256. It uses one shared secret for both signing and verification. It is simple and fast, and it is appropriate when the issuer and the verifier are the same service.

RS256 is RSA with SHA-256. It uses a private key to sign and a public key to verify. It is the right choice when a separate service verifies tokens, because the verifier can be given the public key without the ability to mint tokens.

ES256 is ECDSA with SHA-256. It gives the same properties as RS256 with smaller keys and signatures.

The rule that follows: use HS256 only when the same service signs and verifies. Use RS256 or ES256 when the verifier is a different service, because a shared secret in a verifier is a signing key in disguise.

Verifying a token

A resource server must do more than decode the token. It must verify the signature, and it must check the claims.

import jwt from 'jsonwebtoken';

const claims = jwt.verify(token, publicKey, {
  algorithms: ['RS256'],        // pin the algorithm
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

Pin the algorithm. Passing an explicit algorithms list is what prevents the alg=none attack and the algorithm-confusion attack, where a token signed with HS256 is verified with the public key as if it were an HMAC secret.

Check the issuer and the audience. A token issued for a different service should not be accepted by this one. The audience check is what stops a token from one API being replayed against another.

Check the expiry. A library usually does this, but it is worth confirming, because a clock skew or a misconfigured option can disable it.

Why the format matters

The format of a JWT is what makes it useful and what makes it easy to misuse. The three parts are separated by dots, and each part is base64url-encoded, which is a reversible encoding rather than a compression or an encryption. That single fact explains most of the security advice: the payload is readable, so it must not hold a secret; the header is attacker-controlled, so the algorithm must be pinned; and the signature covers the first two parts, so any change to either invalidates it. A developer who understands the format can reason about a token without a library, which is useful when a token is rejected and the reason is not obvious. The most common debugging step is to decode the three parts and look at the claims, which takes one command and answers most questions about why a token was refused.

Common mistakes

Trusting the alg header. The header is attacker-controlled. The verification call must specify the expected algorithm, not read it from the token.

Using a weak secret. An HS256 secret that is a short word can be brute-forced offline. Use a long random value, at least 256 bits.

Long expiry with no revocation. A token that lives for a week cannot be revoked, so a compromised account stays compromised for a week. Keep the access token short and use a refresh token.

Storing the token in localStorage. Any script on the page can read it, so one XSS vulnerability leaks it. Use an HttpOnly cookie.

Putting sensitive data in the payload. The payload is readable. Treat it as public.

Verifying with the wrong key type. Passing a public key to an HS256 verification, or a secret to an RS256 verification, is the algorithm-confusion bug. Pin the algorithm and the key type.

A quotable summary

A JWT is a signed, self-contained token with three base64url parts: a header, a payload and a signature. The signature proves the claims are authentic and unaltered, but the payload is readable by anyone, so it must never hold a secret. Verification must pin the algorithm and check the issuer, audience and expiry. The main limitation is revocation: a signed token cannot be withdrawn without adding the server-side state that the format was designed to avoid.

For the flow that issues these tokens, see oauth2-explained and for the storage decision, session-vs-token-auth. For the broader context, api-authentication-methods and secret-management-guide.

Frequently asked questions

What is a JWT in simple terms?
A JSON Web Token is a compact string that carries a set of claims, such as a user ID and an expiry, together with a signature. The signature lets a server verify that the claims were issued by a trusted party and have not been altered, without looking up a session in a database.
Is a JWT encrypted?
No, not by default. A standard JWT is signed, which means the content is readable by anyone who has the token. The signature proves the content has not been changed, but it does not hide it. If you need confidentiality, use JWE (JSON Web Encryption), which is a different format.
What is the difference between HS256 and RS256?
HS256 uses a single shared secret to both sign and verify, so every party that can verify a token can also create one. RS256 uses a private key to sign and a public key to verify, so a resource server can verify tokens without being able to mint them. Use RS256 when the verifier is not the issuer.
How do I revoke a JWT?
You cannot revoke a signed JWT by itself, because the server does not keep state. The practical options are a short expiry so the window is small, a refresh token that can be revoked, or a denylist of revoked token IDs checked on each request. The last option reintroduces the state that the JWT was meant to avoid.
Where should I store a JWT in a browser?
The safest place for a browser is not in JavaScript at all. Store it in an HttpOnly, Secure, SameSite cookie so a script cannot read it, and protect the endpoints with CSRF defences. localStorage is readable by any script on the page, so a single XSS vulnerability leaks the token.
What is the alg=none attack?
It is an attack where the token's header claims the algorithm is none, meaning no signature. A server that trusts the header and skips verification accepts a forged token. The fix is to pin the expected algorithm in the verification call and reject anything else.