A JSON Web Token (JWT) is a signed string that carries claims about a user. Servers use it to recognize a returning request without looking up a session in a database. JWTs fit some systems well and cause trouble in others, so it helps to know what one contains and what it cannot do.
The structure of a JWT
A JWT has three parts separated by dots: a header, a payload and a signature.
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0MiIsImV4cCI6MTc2MDAwMDAwMH0.signatureThe header names the signing algorithm. The payload holds claims such as sub (the user ID), exp (expiry time) and iat (issued at). The signature proves that someone with the key created the token and that nobody changed it afterward.
Base64 encoding is not encryption. Anyone who holds the token can read the payload. Never put passwords, personal data or secrets in it.
How the flow works
- The user sends credentials to your login endpoint.
- The server checks them and returns a short-lived access token.
- The client sends the token in an
Authorization: Bearerheader on later requests. - The server verifies the signature and the expiry, then reads the user ID from the payload.
Because verification needs only the key, any service in your system can check a token without calling a central session store. That property makes JWTs useful for microservices and mobile APIs.
Choose the algorithm on purpose
HS256 uses one shared secret for signing and verifying. RS256 and ES256 use a private key to sign and a public key to verify, so only the auth service holds the secret. Use an asymmetric algorithm when several services verify tokens.
Pin the accepted algorithms in your verification code. Older libraries once accepted tokens with alg: none, which let attackers skip the signature. Current libraries reject it, but an explicit allow-list protects you from configuration mistakes.
Keep access tokens short
A JWT stays valid until it expires, even if the user logs out or an admin disables the account. Set access tokens to 5 to 15 minutes. Pair them with a refresh token that lives longer, sits in your database and can be revoked. When the access token expires, the client trades the refresh token for a new pair. Rotate the refresh token on each use and treat a reused one as a sign of theft.
Where to store tokens in a browser
Local storage is readable by any script on the page, so a cross-site scripting bug leaks the token. An HttpOnly, Secure, SameSite=Lax cookie hides the token from JavaScript. Cookies bring cross-site request forgery risk, which SameSite and a CSRF token reduce. For most web apps, a cookie holding the refresh token and an in-memory access token strike a workable balance.
Common mistakes
- No expiry check. Always verify
exp, and also checkissandaudwhen you have several issuers or audiences. - Long-lived tokens. A 30-day access token gives a thief a 30-day window.
- Weak secrets. An HS256 secret needs at least 32 random bytes. Generate it, do not invent it.
- Stuffing the payload. Large tokens add weight to every request. Store the user ID and a role, then load the rest from your database.
- Logging tokens. A token in a log file works as a password.
When sessions are the better choice
A classic server-side session with an opaque ID in a cookie is simpler for a single web application. You can end a session , and the cookie contains nothing to decode. JWTs earn their complexity when many services or clients need to verify identity .
Common questions
Can I revoke a JWT before it expires?
Not by itself, because verification needs only the signature. To revoke, keep access tokens short, store refresh tokens in a database where you can delete them, and add a deny list for the rare case that needs instant cut-off, such as a stolen admin token. The deny list lookup adds the same state a session would, so use it for exceptions only.
Should I put roles and permissions in the token?
A role claim is fine and saves a lookup, as long as you accept that a role change takes effect only when the token refreshes. For fine-grained permissions that change often, store only the user ID in the token and load permissions from your database or a cache on each request.
What is the difference between JWT and OAuth 2.0?
JWT is a token format. OAuth 2.0 is an authorization framework that defines how a client obtains tokens from an authorization server. OAuth often issues JWTs as access tokens, and OpenID Connect adds a signed ID token on top to describe the user. You can use JWTs without OAuth, and you can use OAuth with opaque tokens.
Should I build authentication myself?
Most teams do better with a proven provider or library. Services such as Auth0, Clerk, AWS Cognito and Firebase Authentication handle password hashing, social login, multi-factor authentication and breach detection. Build your own only when you have specific compliance or data residency requirements and the security expertise to maintain it.
If you are designing authentication for a new product, we can help you choose between sessions, JWTs and a hosted provider such as Auth0 or Cognito. See our web and API development services or send us the details.