What is a JWT and how does it work?

May 22, 2026 · 14 min read

A JSON Web Token (JWT) is a compact, URL-safe string that carries claims (facts about a user or session) between parties. Unlike an opaque server-side session ID, a JWT is self-describing: anyone who holds the token can read the payload after Base64URL decoding. Trust comes from a cryptographic signature or encryption, not from hiding the middle segment.

What JWT means in practice

JWTs are defined in RFC 7519 and used with algorithms from the JWA (JSON Web Algorithms) family. You will see them in OAuth 2.0 access tokens, OpenID Connect ID tokens, API gateways, and microservice meshes. The string always has the shape header.payload.signature separated by dots, with each segment encoded in Base64URL without padding.

The three-part structure

The header names the token type (typ, usually JWT) and signing algorithm (alg, e.g. HS256 or RS256). The payload holds claims: registered names like sub (subject), exp (expiry), and iat (issued at), plus custom keys your API defines. The signature proves the first two segments were not tampered with.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

# Decoded header:  {"alg":"HS256","typ":"JWT"}
# Decoded payload: {"sub":"1234567890","name":"John Doe","iat":1516239022}

Signing and who you trust

With HMAC (e.g. HS256), the same secret signs and verifies the token - typical for a single API that issues and checks its own JWTs. With RSA or ECDSA (RS256, ES256), the issuer signs with a private key; verifiers use the public key from JWKS. Changing even one character in the header or payload breaks the signature, which is why validators reject malformed or edited tokens outright.

Typical authentication flow

User authenticates (password, SSO, passkey) and the authorization server issues a JWT access token (and often a refresh token).
The client stores the access token (memory, secure cookie, or mobile keychain - not localStorage for sensitive apps without hardening).
Each API request sends Authorization: Bearer <jwt>.
The resource server validates signature, exp, issuer (iss), and audience (aud) before running handlers.

// Conceptual verify (use a maintained library in production)
import { jwtVerify } from "jose";

const { payload } = await jwtVerify(token, secretOrPublicKey, {
  issuer: "https://auth.example.com",
  audience: "api.example.com",
});
console.log(payload.sub);

What JWTs are not

A JWT is not encrypted by default - the payload is only encoded, not secret. Do not put passwords, credit card numbers, or PII you would not log in the payload unless you use JWE (encrypted JWT). A JWT is also not a session store: once issued, it lives until expiry unless you add revocation (denylist, short TTL, refresh rotation). Treat the token as a signed envelope, not a database row.

FAQ

Is a JWT the same as an OAuth access token?: Often, but not always. OAuth access tokens can be opaque strings; when they are JWTs, they follow the same three-part layout. OpenID Connect ID tokens are always JWTs with specific claims.
Can I read a JWT without the secret?: Yes. Base64URL-decoding the payload requires no key. The secret or public key is only needed to verify the signature.
Why are there two dots in a JWT?: They separate header, payload, and signature. The signed input is literally base64url(header) + '.' + base64url(payload).
What algorithm should new APIs use?: Prefer asymmetric RS256 or ES256 when multiple services verify tokens; use HS256 only when one service both issues and validates with a strong shared secret.

Browse all tools