A rejected JSON Web Token (JWT) can fail for several independent reasons: a malformed token, an unexpected claim, an expired timestamp, an untrusted signing key, or a mismatch between the token and the API’s authentication policy. This guide provides a repeatable JWT debugging workflow, explains the fields worth tracking, and shows how to inspect tokens locally without exposing production credentials or secrets.
Overview
A JWT is usually a compact, dot-separated value with three Base64URL-encoded parts: a header, a payload, and a signature. The header and payload can be decoded for inspection, but decoding does not prove that the token is authentic. The signature must still be validated with a trusted key, and the claims must satisfy the receiving service’s rules.
Most authentication failures fall into one of three categories:
- Transport or formatting: the token is missing, truncated, incorrectly copied, or sent in the wrong header format.
- Validation: the signature, algorithm, issuer, audience, timestamps, or key identifier does not match the API configuration.
- Authorization: the token is valid, but it does not contain the role, scope, tenant, or permission required for the requested resource.
That distinction matters. A 401 Unauthorized response commonly indicates that authentication could not be established or validated. A 403 Forbidden response often means the identity was recognized but lacks permission. Exact behavior varies by framework and gateway, so confirm the interpretation in the relevant service logs and documentation.
What to track
Header fields
| Field | Purpose | Debugging question |
|---|---|---|
alg | Identifies the signing algorithm. | Does the verifier explicitly allow this algorithm, and does it match the issuer configuration? |
typ | Describes the token type when included. | Does the application expect a JWT or a different token format? |
kid | Identifies the signing key used by the issuer. | Can the verifier find this key in the current JWKS document? |
Treat the algorithm as a policy input, not as a value to trust blindly from the token. The verifier should use an explicit allowlist of supported algorithms and should reject unexpected or unsuitable choices. Never “fix” a signature problem by accepting every algorithm or disabling verification.
Claims in the payload
| Claim | Meaning | Common failure |
|---|---|---|
iss | The token issuer. | The configured issuer URL differs in scheme, host, path, or trailing slash. |
aud | The intended recipient or audience. | The API expects a different audience, or the library handles string and array forms differently. |
exp | Expiration time as a NumericDate. | The token has expired, or the system clock is inaccurate. |
nbf | Not-before time. | The token is being used before it becomes valid. |
iat | Issued-at time. | A policy rejects implausible issue times or reveals clock drift. |
sub | Subject identifier. | The application maps the subject to the wrong account or tenant. |
scope or roles | Authorization data defined by the identity system or application. | The token is valid but does not satisfy the endpoint’s permission check. |
Claim names and formats are not universally identical across identity providers. Confirm whether your provider emits permissions in scope, roles, groups, or a custom claim, and confirm whether values are strings, arrays, or nested objects.
Keys and JWKS
For asymmetric signing, the issuer commonly publishes public keys through a JSON Web Key Set (JWKS) endpoint. The verifier selects a key using the token’s kid. During key rotation, an issuer may publish both an older and newer public key for a transition period. Intermittent failures can occur when a gateway caches an outdated JWKS document, when different environments use different issuer URLs, or when a token references a key that the verifier cannot retrieve.
Track the configured issuer, JWKS URL, allowed algorithms, key-cache behavior, and the observed kid values. Do not copy private signing keys into a debugger, browser tool, issue, or chat transcript.
Cadence and checkpoints
Use a consistent debugging sequence rather than changing several authentication settings at once.
- Capture the request shape. Confirm that the client sends
Authorization: Bearer <token>, that only one relevant token is present, and that proxies are not stripping or rewriting the header. Avoid logging the complete token. - Check the token structure. Confirm that it has three dot-separated segments and can be decoded as Base64URL. A decoding failure points to transport, copying, or token-generation problems rather than a signing-key problem.
- Inspect non-secret metadata. Record the header fields and selected claims such as
iss,aud,exp,nbf, andkid. Redact or hash subject identifiers where logs could contain personal data. - Compare validation configuration. Check issuer, audience, algorithm allowlist, JWKS location, required claims, and clock settings in the service actually returning the error. A local development configuration may not match an API gateway or production backend.
- Validate the signature. Use a trusted library and the issuer’s public key set. Do not treat a decoded payload as proof of authenticity.
- Check time behavior. Compare UTC time on the client, gateway, and backend. If a small clock difference is expected, configure narrowly bounded clock tolerance according to the library’s documented behavior rather than ignoring expiration.
- Separate authentication from authorization. If signature and claim validation succeed, inspect scopes, roles, tenant mapping, resource ownership, and endpoint policy.
- Compare a known-good token. Use a freshly issued test token from the same environment and identity flow. Compare configuration-relevant fields, not personal data or full token contents.
For browser debugging, inspect the request headers through developer tools without copying the token into shared tickets. For an API gateway, correlate its request ID with backend logs and determine which component generated the response. For backend debugging, log structured failure categories such as expired, issuer_mismatch, audience_mismatch, unknown_kid, or insufficient_scope without recording the raw credential.
How to interpret changes
A sudden increase in JWT expiration error reports may indicate an actual lifetime change, a device or server clock problem, or clients reusing tokens longer than intended. A rise in unknown-key failures around a deployment suggests a JWKS caching or key-rotation issue. If only one service reports signature failures while others accept the same issuer’s tokens, compare its issuer URL, algorithm policy, network access to JWKS, and cache state.
Issuer and audience mismatches are often environment mix-ups. A staging token sent to production may be correctly signed and still rejected because its iss or aud is wrong. Similarly, a token intended for one API should not automatically be accepted by another API simply because both use the same identity provider.
Do not use a 401 or 403 count alone to diagnose JWT health. Pair authentication error metrics with deployment events, identity-provider changes, key identifiers, issuer and audience configuration versions, and gateway-to-backend request IDs. Redact tokens and minimize claim values in telemetry. Authentication logs should help operators identify a failure class without becoming a source of credential exposure.
Safe local inspection
A local JWT decoder can be useful for formatting a header and payload, but use it only with synthetic, expired, or deliberately redacted tokens whenever possible. Online decoder tools may transmit input to a third party; do not paste production access tokens, refresh tokens, private keys, or confidential claims into them. Prefer a local command-line or library-based workflow, disable shell history where appropriate, and remove temporary files after testing.
When to revisit
Review this checklist during identity-provider integration, API gateway changes, authentication-library upgrades, environment promotion, and every signing-key rotation. A monthly or quarterly review is also useful for teams that operate several services: confirm that allowed algorithms remain intentional, issuer and audience values are documented, JWKS retrieval works from each runtime environment, and token-related logs remain redacted.
Before closing a recurring incident, record the observed error class, affected environment, kid, configuration version, clock condition, and corrective action. Recheck the same path after the next deployment or rotation rather than assuming the fix is permanent.
For a practical final check, verify these items in order:
- The bearer header reaches the intended service.
- The token has the expected structure and environment.
- The algorithm is explicitly allowed.
- The issuer and audience exactly match configuration.
expandnbfare valid with controlled clock tolerance.- The
kidresolves to the expected public key. - The signature validates with a trusted library.
- Scopes, roles, tenant, and resource permissions allow the operation.
- Logs and debugging artifacts contain no reusable production credentials.
Authentication behavior changes over time as services, libraries, identity providers, and keys change. Keeping these checkpoints in a runbook turns JWT debugging from ad hoc token inspection into a safer, repeatable developer tool workflow.