How it works
A JWT (pronounced 'jot') is three base64url-encoded parts joined by dots: a header naming the signing algorithm, a payload of claims (sub for the user id, exp for the expiry time, iss for the issuer, plus custom ones such as role) and a signature. It is signed either with a shared secret (HS256, an HMAC) or with a private key (RS256, ES256), in which case anyone can verify it with the public key, usually published at a JWKS URL.
The payload is encoded, not encrypted, so anyone holding the token can read it and it must never contain secrets. The central trade-off is revocation: a valid JWT keeps working until it expires, even after the user signs out or is banned. Systems therefore issue short-lived access tokens (minutes to an hour) with a refresh token that gets new ones, or keep a deny list, which brings back the lookup JWTs were meant to avoid.
Supabase, Firebase and Clerk all give apps JWTs, and OpenID Connect ID tokens are JWTs. Verifying code must check the algorithm, signature, expiry and audience; libraries that once accepted the 'none' algorithm or confused key types led to real vulnerabilities. Tokens kept in localStorage are exposed to any cross-site scripting (XSS) bug, so HttpOnly cookies are often the safer place for them in a browser.
JWT pros and cons
Pros
- Any server with the key can verify it without a database lookup
- Works across domains, mobile apps and separate services
- A standard format (RFC 7519) with libraries for every language
- Carries roles and other claims that database rules can read directly
Cons
- Hard to revoke before it expires
- Readable by anyone who holds it, so no secrets in the payload
- Grows with every claim and travels with every request
- Easy to misconfigure: algorithm, audience and expiry checks all matter
When to use JWT
Pick it when
- APIs called by mobile apps or other services
- Several services must trust one sign-in without a shared session store
- Your auth provider issues JWTs and your database rules read them, as with Supabase
Skip it when
- A single web app with its own server, where a session cookie is simpler
- You need instant sign-out and do not want short lifetimes and refresh logic
JWT vs the alternatives
Related terms
More in Auth and identity
Tokens and sessions