JWT Lifecycle

JSON Web Tokens (JWTs) are a standard mechanism for representing claims securely between a client and a server.

Mental Model

The primary benefit of JWTs is stateless authentication: once the Identity Provider (IdP) verifies a user’s credentials and signs a token, resource APIs can validate that token locally using cryptographic keys without querying the authorization server or database on every request. A client authenticates with the Auth Server, which issues a short-lived access token and a long-lived, database-backed refresh token. The client includes the access token in the Authorization header of API requests, allowing the Resource Server to statelessly verify the token signature and claims. If the access token expires, the client uses the refresh token to request a new one, rotating the refresh token to maintain security. Logging out invalidates the stateful refresh token to block new access token generation.

Components and Why They Exist

Client (Browser/App)

The end-user application requesting access to secure resources. Submits credentials, stores the access and refresh tokens (e.g. in secure cookies or memory), and attaches the JWT to the Authorization header on API requests. In the demo, watch it transition from Unauthenticated to Authenticated, send API calls, and handle token refresh.

Auth Server (IdP)

The Identity Provider responsible for authenticating users and issuing tokens. Verifies user credentials against the database, issues signed JWT access tokens and database-backed refresh tokens, and manages token refresh requests. In the demo, watch it verify users in the database, sign tokens, and issue fresh JWTs.

Resource Server (API)

The server hosting secure data that the client wants to access. Performs stateless validation of the incoming JWT (verifying the signature, expiration, and audience claims) and serves resources on success. In the demo, watch it validate tokens locally and return either 200 OK or 401 Unauthorized for tampered or expired tokens.

Database (Users)

The permanent store of user records and refresh token whitelist/blacklist states. Stores user credentials (hashed) and tracks refresh token revocation states. In the demo, watch verification queries during login, and watch refresh token revocation status updates during refresh and logout steps.

Edge Cases and Misconceptions

• Misconception: JWT payload data is encrypted: A JWT is base64url encoded, NOT encrypted. Anyone who intercepts the token can decode it to view the payload claims. Sensitive data (like passwords or personally identifiable information) should never be stored in a standard JWT payload.
• Misconception: A stateless JWT can be easily revoked: Because resource servers validate JWTs statelessly (locally by signature), there is no simple way to revoke an active access token before it naturally expires. Access tokens must have a very short lifespan (e.g., 5 to 15 minutes) to minimize the abuse window.
• Edge Case: Token Tampering: If an attacker alters any claims in the JWT payload (e.g., modifying the user role from user to admin), the signature validation on the Resource Server will fail because the signature was generated using the original payload bytes.
• Edge Case: Token Replay: If a JWT is intercepted by a malicious third party, they can replay it to access the APIs. To mitigate this, runtimes must enforce HTTPS, use secure cookies with HttpOnly/SameSite attributes, and assign short token lifespans.