2026-06-30 · 6 min read · Rahul Chitturi
- jwt
- auth
- debugging
Audience and issuer errors usually mean the token was real, but it was not meant for the API that received it. That distinction matters: rotating keys or loosening verification can hide the symptom while leaving the wrong trust boundary in place.
Start by decoding a non-production token, reading the claims as data, and comparing them with the verifier configuration that rejected the request.
Read aud and iss exactly
The issuer identifies who created the token. The audience identifies the API or resource server that should accept it. Both values are exact strings in most libraries, so an environment suffix, tenant path, trailing slash, or regional issuer can break otherwise valid authentication.
- iss should match the configured identity provider or tenant URL
- aud should match the API identifier expected by the backend
- azp or client_id may describe the app, not the resource audience
- Multiple audiences can be valid only when your verifier expects that shape
Separate environment drift from token bugs
A staging frontend can accidentally request a production audience, or a preview deployment can reuse a local client ID. The rejected token may be perfectly signed for a different environment. Compare issuer, audience, client ID, and API base URL together before editing middleware.
When a bug affects only one customer tenant, check whether the issuer includes a tenant-specific segment and whether the API allowlist matches that tenant.
Do not skip lifetime checks
After aud and iss match, verify the time claims. Expired, not-before, or issued-at errors can appear beside audience failures in gateway logs. Convert exp, nbf, and iat from Unix seconds to human time so you can compare them with deployment and incident timelines.
A Flashman workflow
Decode a test token with the JWT tool, format any provider metadata JSON, and diff the working and failing claim sets. Use the timestamp converter for exp and nbf so the team can reason about exact instants instead of raw epoch numbers.
Keep production tokens out of tickets. If you need to share a reproduction, create a synthetic token with the same claim names and non-secret placeholder values.