JWT Debugging Guide: Decode Claims, Verify Signatures, and Fix Authentication Errors
jwtauthenticationapissecuritybackenddebugging

JWT Debugging Guide: Decode Claims, Verify Signatures, and Fix Authentication Errors

DDev Tools Studio
2026-11-20
7 min read

A practical JWT debugging checklist for decoding claims safely, verifying signatures, and fixing expiry, issuer, audience, and header errors.

A JWT can be structurally valid and still be rejected by an API. This guide gives you a reusable workflow for inspecting claims safely, separating decoding from signature verification, and diagnosing expiration, issuer, audience, algorithm, clock-skew, header, and authorization errors without exposing live credentials.

Overview

JSON Web Tokens are compact, URL-safe strings usually made of three dot-separated parts:

header.payload.signature

PartPurposeTypical fields
HeaderDescribes how the token is handledalg, typ, kid
PayloadContains claims about the subject, issuer, and token lifetimesub, iss, aud, exp, iat, scope, roles
SignatureAllows the verifier to detect tamperingDepends on the signing algorithm and key

Decoding the first two parts only reads data. It does not prove that the token was issued by a trusted authority or that its claims are acceptable to your API. Verification checks the signature and should also enforce the expected issuer, audience, algorithm, and time-based claims. Treat every decoded claim as untrusted until verification succeeds.

For a safe inspection workflow, copy a redacted token into a local development utility or a trusted browser-based JWT decoder only when it contains no production secrets or personal data. A signed JWT is often readable by anyone who possesses it, even when it cannot be modified successfully.

Checklist by scenario

The token will not decode

  • Confirm that the value has exactly three dot-separated segments.
  • Remove the Bearer prefix before passing the token to a decoder.
  • Check for copied quotation marks, line breaks, spaces, or URL encoding.
  • Remember that JWT segments use base64url encoding, not ordinary JSON text.
  • Compare the token captured by the client with the token actually received by the server.

A malformed token usually points to transport or storage handling rather than a cryptographic problem. Inspect the request in your browser’s Network tab or API client, and log only safe metadata such as segment count and token length. Do not log the complete token.

The API reports an expired token

  • Decode exp and compare it with the server’s current Unix time in seconds.
  • Check whether the client is sending an old access token from storage or a cached request.
  • Inspect iat and nbf for tokens issued in an unexpected time window.
  • Verify that refresh logic replaces the access token and does not repeatedly retry with the same value.
  • Check clock synchronization on the client, API, identity provider, and any gateway.

Do not solve an expiration failure by accepting tokens indefinitely. If a small clock tolerance is necessary, configure it deliberately on the verifier and monitor the underlying time discrepancy.

The signature is invalid

  • Confirm that the verifier is using the correct public key or shared secret for the environment.
  • Allow only the algorithms your service intentionally supports; do not trust an arbitrary alg value from the token.
  • Use the header’s kid, when applicable, to select the matching key from the configured key set.
  • Check for key rotation, stale key caches, and mismatched development and production configuration.
  • Make sure the token has not been altered by a proxy, test script, or manual copy.

A signature failure is not fixed by changing payload claims. Compare the identity provider’s signing configuration with the API verifier’s algorithm and key configuration. Keep private signing keys out of browser code, source control, logs, and client-side debugging tools.

The signature is valid but claims are rejected

  • Compare iss with the exact issuer configured for the API.
  • Compare aud with the API’s expected audience. An access token for one service may not be valid for another.
  • Check whether the API expects a string, array, or particular naming convention for scopes or roles.
  • Confirm that the subject in sub maps to an active local account or permitted service identity.
  • Distinguish authentication failure from authorization failure: a valid identity can still lack the required permission.

Claim names are not universal application permissions. Document which claims your API consumes, their accepted types, and the decision made when a claim is missing. Avoid silently treating a missing role or scope as an administrator-level permission.

The server says the token is missing

  • Verify the request contains Authorization: Bearer <token> with one space between the scheme and value.
  • Check whether a reverse proxy, gateway, or serverless adapter removes the authorization header.
  • Confirm that the browser request is using the intended API origin and that your client interceptor runs for that origin.
  • For cookie-based authentication, inspect cookie domain, path, secure, and same-site behavior without printing the cookie value.
  • Compare a failing request with a known-good request at the network boundary.

Browser storage is often part of this investigation. The browser storage debugging guide can help you inspect where a token is held and whether a stale value is being reused.

What to double-check

Decode versus verify

A decoder can show you the header and payload, but it cannot establish trust. In a backend implementation, use a maintained JWT library and pass verification options explicitly. Conceptually, the verification flow should look like this:

const claims = await verify(token, verificationKey, {
  algorithms: ["RS256"],
  issuer: expectedIssuer,
  audience: expectedAudience
});

The exact API differs by language and library. The important decisions are that the allowed algorithm is fixed by configuration, the key comes from a trusted source, and issuer and audience checks are enabled rather than inferred from the token.

Request and response evidence

Record a correlation ID, route, status code, verifier error category, issuer configuration version, and key identifier. Avoid recording the raw token, authorization header, refresh token, or sensitive payload values. A 401 commonly indicates missing or invalid authentication; a 403 commonly indicates that authentication succeeded but the identity lacks access, although your framework may use different conventions.

Identity-provider configuration

When integrating a new provider, compare the provider’s discovery or key configuration with your application settings. Confirm the issuer URL, audience or resource identifier, signing algorithm, key endpoint, required scopes, and token type. Small differences in trailing slashes, tenant identifiers, or environment URLs can produce claim and signature errors that look unrelated.

For broader request troubleshooting, the Chrome DevTools Network Tab guide provides a useful method for comparing headers, redirects, cookies, and response details.

Common mistakes

  • Trusting decoded roles. A role visible in the payload is not permission until the token is verified and the role is mapped according to application policy.
  • Accepting every algorithm. Algorithm selection belongs in server configuration, not in an untrusted token header.
  • Using an ID token as an access token. These tokens can have different audiences and intended consumers. Use the token type specified by the identity system and API design.
  • Logging complete tokens. Logs, error trackers, terminal history, screenshots, and support tickets can become credential leakage points.
  • Changing several variables at once. Change one configuration item, reproduce the request, and record the result. Otherwise, you may hide the original cause.
  • Retrying forever after a 401. A client should prevent refresh loops and require a clear sign-in path when refresh fails.
  • Testing only the happy path. Include expired, malformed, wrong-audience, wrong-issuer, missing-scope, rotated-key, and absent-header cases in integration tests.

If the failing request is generated by a webhook or callback rather than a browser, inspect its signature and retry behavior separately; the webhook debugging guide covers that adjacent workflow.

When to revisit

Return to this checklist whenever you change an identity provider, API gateway, framework adapter, JWT library, signing algorithm, key-rotation process, domain, audience, or authorization model. It is also worth revisiting before a major release or seasonal planning cycle, when access rules and operational ownership may change.

Run this short review before shipping:

  1. Verify a valid token and confirm the expected issuer, audience, algorithm, and key.
  2. Test an expired token, malformed token, wrong-audience token, and token with insufficient scope.
  3. Test key rotation and confirm that old and new keys behave according to your planned transition.
  4. Inspect production logs to ensure they contain diagnostic context but no credentials.
  5. Confirm client refresh behavior stops cleanly after failed authentication.
  6. Update the runbook with the current verifier configuration, ownership, and safe reproduction steps.

Keep a redacted sample token for each test case, or generate fixtures locally, rather than saving real user tokens. JWT debugging becomes faster and safer when the team can reproduce the same claim and verification conditions without handling live credentials.

Related Topics

#jwt#authentication#apis#security#backend#debugging
D

Dev Tools Studio

Senior SEO Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.