Developer tools · JWT decoder
Debugging a 401: What to Check in a Decoded JWT Before Blaming the API
· Why it matters
jwt debugging authentication
Most token rejections come down to a handful of claim problems you can spot by reading the payload. This post gives a checklist, from expiry to audience to copy-paste errors, in the order to check them.
It worked yesterday — the 401 that appears with no code change
A 401 that appears without a client code change can originate in token age, issuer policy, key rotation, audience selection or a damaged copy. Start with evidence rather than assuming the API is down. Preserve the response details and correlation identifiers before manipulating the credential.
Decode only an expired, synthetic or appropriately controlled copy. ToolAcre can expose structural and claim clues, but it cannot identify every server rejection because it has no key, issuer policy or API logs. The checklist narrows questions; it does not replace the resource server’s verdict.
Copy errors first — 'Bearer ' prefixes, trailing newlines and truncated tokens
Check the copied value first. ToolAcre trims surrounding whitespace and removes one case-insensitive `Bearer ` prefix, which handles a common Authorization-header paste. It then requires exactly three dot-separated segments. A wrong count points toward truncation, the wrong token form or extra punctuation before claim analysis begins.
An empty header or payload fails specifically. Invalid base64url, invalid UTF-8 and invalid JSON have separate errors. Those distinctions help determine whether transport damaged the token. The signature may be malformed without blocking inspection, but that warning remains a likely verification failure requiring server-side confirmation.
exp and nbf: inspect seconds-based values without turning the display into a validity verdict
Inspect numeric `exp` and `nbf` values next. ToolAcre multiplies seconds by 1,000, shows UTC and labels an earlier expiry or future not-before relative to the browser clock. A thirteen-digit value may reveal milliseconds were written where seconds were expected.
Do not promote these labels to enforcement. A forged token can claim a future expiry, and the server may use a different clock or leeway policy. The display identifies arithmetic worth comparing with trusted logs; cryptographic verification must succeed before the claims can influence acceptance.
aud and iss — is this token for this API, from the issuer this API trusts?
`aud` should identify the intended recipient under the API’s policy, while `iss` should match the trusted issuer relationship. ToolAcre lists both as decoded values and explains their registered meanings. It does not compare them with an API configuration or bind an issuer string to a key set.
A plausible issuer URL and audience name can be fabricated. Compare exact decoded values with the server’s configured expectations only after preserving the signature-verification boundary. If several services share identity infrastructure, audience checks are especially important for preventing a valid token for one service being used at another.
Token type may be suggested by headers and claims, but decoding cannot authenticate that classification
An ID token and an access token can both look like three-part JWTs. Header `typ`, audience, scopes and profile-specific claims may suggest which one you hold. ToolAcre warns about an unexpected string `typ`, but it does not implement OpenID Connect or OAuth token classification.
Use issuer documentation and the client flow to establish the expected token kind. Sending an ID token to an API can fail even when its signature is valid for the identity provider. Decoding supports diagnosis; it cannot authenticate the type label or grant API authority.
kid after key rotation — a valid token that references a key the server no longer has
After key rotation, a header `kid` may refer to a key absent from the server’s current trusted set. Read the identifier, then inspect cache and key-set logs on the verifier. Do not fetch a header-provided URL or accept embedded key material as a quick workaround.
A correctly signed token may still fail if the verifier cannot locate the permitted key, while an attacker can write any `kid` into an unverified header. The value is a lookup hint constrained by trusted issuer configuration, not evidence that a particular key should be believed.
Worked example — running a rejected token through the checklist in the ToolAcre JWT decoder
For a worked triage, take a controlled rejected token, confirm three segments, inspect errors, then record `exp`, `nbf`, `aud`, `iss`, `typ` and `kid` without editing it. Compare each field with the request’s target API and the verifier’s trusted configuration. Keep server logs open for the actual failure category.
If all visible values look expected, do not conclude that the API is wrong. Signature corruption, wrong key material, revoked state or unshown policy can still explain the 401. ToolAcre’s `signatureVerified` remains false regardless of how tidy the JSON appears.
What this does not cover and the takeaway — a decoder cannot tell you whether the signature is valid; the checklist finds claim problems, and signature failures need server logs
A decoder cannot tell you whether the signature is valid. Its claim checklist finds copy and payload problems that are visible without a key; signature failures and authoritative policy decisions need server evidence. Treat a decode as one diagnostic observation among several.
The fastest reliable path is ordered: preserve response context, inspect token shape, compare time units, then compare issuer, audience, type and key identifier with trusted configuration. Stop short of trust until the real verifier confirms cryptography and policy.