What is the difference between an access token and a refresh token?

An access token is short-lived and sent on every API request to prove who you are. A refresh token is long-lived, kept securely, and used only to obtain new access tokens without forcing the user to log in again.

Why should access tokens expire so quickly?

JWTs are stateless, so a leaked access token works until it expires. A short TTL like 15 minutes bounds the damage, while the refresh token keeps the session alive so users are not constantly logged out.

What does refresh token rotation protect against?

With rotation, each refresh issues a brand-new refresh token and invalidates the old one. If a stolen refresh token is replayed after the real client has already rotated, the reuse is detected and the whole token family can be revoked.

How do I revoke a stateless JWT?

You cannot un-sign an issued JWT, so you maintain a denylist of token IDs (jti) until their expiry, or revoke the refresh token so no new access tokens can be minted. The short access TTL then closes the remaining window.

Is the JWT payload encrypted?

No. A standard signed JWT is base64url-encoded, not encrypted, so anyone can read the claims. Never put passwords or secrets in the payload; the signature only guarantees the claims were not tampered with.

JWT Authentication Spec Builder

Design a JWT auth flow that is actually secure

JSON Web Tokens are easy to mint and easy to get wrong. The dangerous parts are not the encoding — they are the lifetimes, the revocation story, and the verification rules. This builder produces a spec that pins down all of them: which algorithm signs the token, what claims it carries, how long access and refresh tokens live, how refresh works, and what happens on logout or compromise.

How it works

The spec starts with signing. Symmetric algorithms (HS256) use one shared secret to both sign and verify, which is simple but means every verifier holds the signing key. Asymmetric algorithms (RS256, ES256) sign with a private key and verify with a public one, so resource servers verify via a JWKS endpoint without ever holding the secret. Either way the spec insists you pin the expected alg on verification and reject alg: none — skipping this enables the classic algorithm-confusion attack.

Next it lays out claims. Registered claims (iss, aud, exp, iat, nbf) bind the token to an issuer and audience and define its validity window; your custom claims (like sub, role, jti) carry app data. Because the payload is only base64-encoded, the spec warns against putting secrets in it. Then it sets the two TTLs: a short access-token lifetime sent on every call, and a long refresh-token lifetime used only at POST /auth/refresh. The refresh flow validates the refresh token and, if rotation is enabled, issues a fresh one while invalidating the old — turning replay of a stolen token into a detectable reuse event.

Revocation and error codes

Stateless tokens can’t be un-issued, so revocation works by denylisting jti values until they expire and by killing the refresh token so no new access tokens can be minted. The short access TTL bounds how long a revoked session keeps working. Finally the spec fixes the error contract: 401 for a missing, malformed, or expired token; 403 for a valid token that lacks the required role or scope; and 401 invalid_grant when a refresh token is expired, reused, or revoked.

JWT Authentication Spec Builder

Email me this result

Design a JWT auth flow that is actually secure

How it works

Revocation and error codes