A JSON Web Token (JWT, often pronounced "jot") is a compact, URL-safe string that carries a set of claims, such as who a user is and when the token expires. It is defined in RFC 7519. Most JWTs you meet in practice are signed tokens (JWS, RFC 7515): the content is readable by anyone, but a signature lets the receiver check that it was issued by someone holding the right key and has not been changed. JWTs are widely used as access tokens in APIs and as ID tokens in OpenID Connect.

The three parts of a JWT

A signed JWT is three segments separated by dots:

header.payload.signature

Header

A JSON object that describes the token. It almost always contains alg (the signing algorithm, for example HS256) and often typ (usually JWT). It may also contain kid, a key ID that tells the receiver which key to use for verification.

Payload

A JSON object holding the claims. Some claim names are registered in the standard (see below); the rest are application-specific, such as a role or a tenant ID.

Signature

The result of signing the string base64url(header) + "." + base64url(payload) with the algorithm named in the header. It is Base64url-encoded as well.

Base64url encoding

Each segment is encoded with Base64url, a variant of Base64 that is safe inside URLs and HTTP headers. It differs from standard Base64 in three ways: + becomes -, / becomes _, and the trailing = padding is removed. This is encoding, not encryption. Anyone who has the token can read its header and payload.

Registered claims

RFC 7519 defines seven registered claim names. All are optional, but most systems use several of them:

  • iss (issuer): who created and signed the token, for example the URL of an auth server.
  • sub (subject): who the token is about, usually a user ID.
  • aud (audience): who the token is intended for. A receiver should reject tokens whose audience does not include itself.
  • exp (expiration time): the moment after which the token must not be accepted.
  • nbf (not before): the moment before which the token must not be accepted.
  • iat (issued at): when the token was created.
  • jti (JWT ID): a unique identifier, useful for detecting replay or for revoking individual tokens.

The time claims exp, nbf and iat are NumericDate values: seconds since 1970-01-01 00:00:00 UTC (Unix time), not milliseconds.

A worked example

Here is a complete token, signed with HS256 and the demo secret demo-secret-do-not-use:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLTQyIiwiYXVkIjoiYXBpLmV4YW1wbGUuY29tIiwiaWF0IjoxNzY3MjI1NjAwLCJuYmYiOjE3NjcyMjU2MDAsImV4cCI6MTc2NzIyOTIwMCwianRpIjoiYTFiMmMzZDQiLCJyb2xlIjoiZWRpdG9yIn0.AmGwEAVEBNDDQk47iPgQpSV_5qETPu5NLDCdBbOyKMU

The first segment, eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9, decodes to the header:

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

The second segment decodes to the payload:

{
  "iss": "https://auth.example.com",
  "sub": "user-42",
  "aud": "api.example.com",
  "iat": 1767225600,
  "nbf": 1767225600,
  "exp": 1767229200,
  "jti": "a1b2c3d4",
  "role": "editor"
}

iat and nbf are 2026-01-01 00:00:00 UTC and exp is one hour later, 2026-01-01 01:00:00 UTC, so this token is already expired. The third segment is the HMAC-SHA256 of the first two segments joined by a dot, using the demo secret. Change a single character of the payload and the signature no longer matches.

You can paste the token into the JWT Decoder to see the header and payload as formatted JSON along with the expiry status. You can also decode a single segment with the Base64 Decoder; if a strict decoder rejects it, replace - with +, _ with /, and add = until the length is a multiple of 4.

Signing algorithms: HS256 vs RS256

HS256 (HMAC with SHA-256)

A symmetric algorithm. The same shared secret is used to create and to verify the signature. It is simple and fast, but every service that verifies tokens also holds the secret and could therefore issue tokens. The secret must be long and random; a short or guessable secret can be brute-forced offline from any captured token.

RS256 (RSA signature with SHA-256)

An asymmetric algorithm. The issuer signs with a private key, and anyone can verify with the matching public key. Services that only need to check tokens never see the private key. Identity providers usually publish their public keys as a JWK Set (a JSON document of keys), and the kid header tells the verifier which one to use. ES256 (ECDSA) works the same way with smaller keys and signatures.

Decoding is not verifying

Decoding means reversing the Base64url encoding to read the JSON. It needs no key and proves nothing. Verifying means recomputing or checking the signature with the expected key and algorithm, and then validating the claims: exp and nbf against the current time, and iss and aud against the values your application expects. Only a verified token should be trusted.

The TeqCave JWT Decoder decodes only. It does not check signatures, so a token that decodes cleanly there may still be forged. Use it for debugging, and let your application or a maintained JWT library do the verification.

Security pitfalls

The "none" algorithm and algorithm confusion

The JWT specification allows "alg": "none" for unsecured tokens with an empty signature. Some older libraries accepted such tokens when asked to verify, letting an attacker strip the signature and edit the payload. A related bug is algorithm confusion: a server expecting RS256 is sent a token with HS256, and a vulnerable library uses the RSA public key as the HMAC secret. The fix for both is the same: configure the verifier with an explicit allow-list of algorithms and never let the token's header decide.

Never put secrets in the payload

Because the payload is only encoded, anything in it, such as email addresses, internal IDs or permissions, is visible to whoever holds the token, including browser extensions and logs. Do not put passwords, API keys or other sensitive data in a JWT. If the contents must be confidential, use an encrypted token (JWE) or keep the data on the server.

localStorage vs cookies

A token in localStorage or sessionStorage can be read by any JavaScript on the page, so a single cross-site scripting (XSS) flaw can leak it. A cookie marked HttpOnly cannot be read by JavaScript, and Secure keeps it off plain HTTP. Cookies, however, are sent automatically by the browser, so you need cross-site request forgery (CSRF) protection, typically the SameSite attribute plus a CSRF token where needed. Neither option is safe if the site has XSS; HttpOnly cookies just make direct token theft harder.

Expiry and revocation

A signed JWT stays valid until it expires, even if the user logs out or their permissions change, unless the server keeps extra state. Keep access tokens short-lived, always set and check exp, and use refresh tokens or a jti deny list when you need earlier revocation. Allow only a small clock-skew tolerance when checking times.

FAQ

Is a JWT encrypted?

No. A normal signed JWT (JWS) is only Base64url-encoded, so anyone who has the token can read the header and payload. Encrypted tokens exist (JWE), but they have five parts instead of three and are a different format.

Can I trust a JWT just because it decodes correctly?

No. Decoding only shows what the token claims. Your server must verify the signature with the expected key and algorithm and check exp, nbf, iss and aud before it trusts any claim.

How do I invalidate a JWT before it expires?

A JWT is valid until exp unless the server checks something else. Common approaches are short-lived access tokens with refresh tokens, a deny list keyed by the jti claim, or rotating the signing key, which invalidates every token signed with the old key.