2026-07-22 · 6 min read · Rahul Chitturi
- jwt
- auth
- debugging
A JWT 401 during key rollover can look like a token bug even when the token is valid. The header points to a new kid, the identity provider publishes a refreshed JWKS, but an API gateway, edge cache, or backend process is still using the old key set.
The safest investigation starts with metadata, not secrets. Decode the token header and claims locally, collect the issuer discovery document, and record the cache age of every component that verifies the token.
Trace the key selection path
The kid value only helps if every verifier fetches the same JWKS URI and refreshes it on a reasonable schedule. A stale cache or mismatched issuer can reject a token that another service accepts.
- Decode the JWT header and confirm alg and kid match the intended provider
- Verify iss and aud against the API configuration that rejected the request
- Check JWKS cache TTLs, startup-only fetches, and failed refresh logs
- Compare the failing token time window with the provider key rotation event
Avoid risky auth changes during triage
Do not disable signature verification to make an incident disappear. If a temporary mitigation is needed, prefer a controlled JWKS cache refresh or a rollback to the previous configured issuer over accepting unsigned or mismatched tokens.
When sharing examples with teammates, redact the signature and sensitive claims. Header fields, timestamps, issuer, audience, and kid are usually enough to debug the rollover path.
A Flashman workflow
Use the JWT decoder to inspect token headers and claims, the JSON formatter for discovery and JWKS documents, the timestamp converter for exp, nbf, and iat windows, and the diff tool to compare verifier configuration.
A good postmortem names the stale layer, the expected cache behavior, and the alert that will fire before the next key rotation causes customer-visible 401s.