JWT / authentication error guide
Separate JWT authentication errors by expiry, audience, and signature
Do not mistake a decoded payload for authentication. Check exp, issuer, audience, signature, and syntax as separate boundaries.
Separate decoding from authentication
A readable header and payload do not prove a valid signature. Signature verification needs the relying service's trusted key and algorithm configuration; issuer and audience must also match the receiving contract.
header.payload.signature
exp / iat → time claims
iss → issuer contract
aud → service audience contract
signature → separate verification| Boundary | What to check |
|---|---|
exp / iat | Check expiry and future issued-at separately from signature verification. |
iss | Check that the issuer is allowed by the receiving service. |
aud | Check that the token targets the service's audience contract. |
| Signature | Do not use an unverified decode as authentication. Do not fetch JWKS or guess keys here. |
| Syntax | Reject an invalid three-part, base64url, or JSON structure fail-closed. |
Do not enter secrets
Do not paste a production JWT, refresh token, cookie, or signing secret into this guide. For support, use a fixture or a fully harmless example and keep its contents out of the confirmation note.
This guide and the existing inspector only decode locally. They do not verify signatures, retrieve JWKS, check revocation, or send data externally.
Review cases
| case | outcome | check |
|---|---|---|
expired-or-future | attention | Check exp/iat only; do not call the token signature-verified. |
issuer-audience | mismatch | Compare iss and aud with the service contract. |
signature-unverified | reject-as-auth | Do not authenticate from decoded output; return to key and algorithm configuration. |
malformed-token | reject | Do not treat invalid syntax or JSON as success. |
Use a safe fixture
Use the existing JWT inspector when you need to view header, payload, or time claims locally. This guide is not an authenticator; it supplies an error classification and sharing boundary.