2026-06-26 · 6 min read · Rahul Chitturi
- jwt
- auth
- debugging
A JWT can decode cleanly and still fail verification with invalid signature. That usually means the verifier used a different key, algorithm, or token bytes than the issuer used when it signed the token.
After a secret rotation or identity provider change, resist the urge to loosen verification. Capture a non-production token, inspect the header and claims, and compare the exact environment configuration before changing auth logic.
Start with the header
The JWT header tells the verifier which algorithm was expected and may include a kid value that selects a key from a JWKS endpoint. If the token says RS256 but a service is configured for HS256, or if the kid points to an old key, every request can fail even when the payload looks right.
- Check alg against the verifier allowlist
- Compare kid with the current key set
- Confirm the issuer and audience match the environment
- Verify the token has not been copied with whitespace or missing segments
Separate rotation bugs from encoding bugs
Secret rotation failures often look like encoding mistakes because both produce the same signature error. Base64url padding, copied line breaks, URL encoding around bearer tokens, and truncated logs can all alter the bytes being verified.
Decode the header and payload for inspection, but do not edit them and reuse the signature. Any change to the first two segments requires a new signature from the issuer.
Diff environment configuration
When staging passes and production fails, compare the issuer URL, JWKS URL, client ID, audience, algorithm policy, and cache duration. A stale key cache can keep rejecting new tokens until it refreshes, while a too-short cache can overload the provider during incidents.
- Document the active and previous signing keys during rotation
- Keep key IDs stable enough for overlap windows
- Avoid mixing symmetric secrets and public keys in the same verifier path
- Redact secrets before sharing config diffs
A Flashman workflow
Use the JWT decoder to inspect non-production header fields and claims, the Base64 tool to check copied token segments, the JSON formatter for JWKS responses, and the diff tool to compare verifier config across environments.
Flashman keeps this loop in your browser. Prefer synthetic tokens when possible, redact secrets from examples, and keep signature verification strict once the rotation mismatch is fixed.