JWT token validation sequence
Client requests protected resource using access token, server validates signature.
Every API behind authentication validates JWTs on every request, but teams often gloss over the details: how does the token travel, where is the signature verified, what happens when it expires? This template lays out the validation sequence in nine steps: the client request with the token, the API extracting it, the auth service checking both signature and expiry, and two outcome paths — valid token proceeds to permission checks and the actual request is served; expired or invalid token returns 401 and the client must refresh.
When to use this template
- Designing a token strategy — decide where validation happens (API gateway or individual services), whether every service validates locally or calls a central auth service, and how you handle revocation during a security incident.
- Onboarding new backend engineers — show them the request → validation → response cycle so they understand why expired tokens return 401 and where to add logging for auth failures.
- Security reviews and compliance — auditors need to see validation is enforced on every request and that signature checks are in place. This diagram answers both questions clearly.
How to adapt it
Start by mapping validation to your real architecture:
- Replace the generic AuthService with your actual system (Auth0, Okta, a custom token verifier).
- Add a token refresh flow if clients need to renew expired tokens without re-authenticating — show the refresh endpoint and how a new access token is issued.
- Insert permission or scope checks after validation if your API gates features by role — show the check against the token's claims and the response when access is denied (403 Forbidden).
Visual edits regenerate clean Mermaid code, so you can adapt the diagram right in the editor and copy the result into your API documentation or design docs.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
actor Client
participant API
participant AuthService
Client->>API: GET /protected + Authorization header
API->>API: Extract JWT from header
API->>AuthService: Validate signature + expiry
AuthService-->>API: Valid (decoded claims)
API->>API: Check permissions from claims
API-->>Client: 200 + resource data
Client->>API: GET /protected (expired token)
API->>AuthService: Validate signature + expiry
AuthService-->>API: Token expired
API-->>Client: 401 Unauthorized
Frequently asked questions
- What is a JWT token validation sequence diagram?
- It maps how a server validates a JSON Web Token (JWT) when a client requests a protected resource. The sequence shows the client sending the token in an Authorization header, the API extracting and verifying the signature, the auth service checking expiry and permissions, and the two outcomes: valid token (200 response) or expired token (401). It makes the validation steps and error paths explicit for the whole team.
- Why validate JWT signature on every request?
- The signature proves the token wasn't forged and hasn't been tampered with since the auth server issued it. Validating on every request ensures a revoked token can't be used again (though long-lived tokens introduce a revocation delay — refresh-token rotation addresses this). Skipping validation would let any attacker forge tokens.
- How do I extend this diagram to show token refresh?
- Add a second sequence after the 401: the client sends a refresh token to a /refresh endpoint, the auth service issues a new access token, and the client retries the original request with the fresh token. This shows teams how refresh flows prevent users from being logged out mid-session when an access token expires.
- What is the difference between the signature check and the expiry check?
- The signature verifies the token came from your auth server and hasn't been modified — it's cryptographic. The expiry check is a timestamp comparison: if the `exp` claim is in the past, the token is no longer valid, even if the signature is correct. Both must pass for a token to be accepted.