JWT Decoder Guide: How to Inspect Tokens Safely and Debug Authentication Errors

Overview

JSON Web Tokens (JWTs) are compact strings commonly used to carry authentication or authorization data between a client and an API. A signed JWT usually contains three dot-separated parts: a header, a payload, and a signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJleHAiOjE3MDAwMDAwMDB9.signature

The header describes the token type and signing algorithm. The payload contains claims such as a subject, issuer, audience, issued-at time, and expiration time. The signature allows the receiving service to verify that the signed content has not been changed and that it was produced with the expected key.

A JWT decoder reads the header and payload so you can inspect their contents. It does not, by itself, prove that the token is authentic. Decoding is generally a representation step; validation requires checking the signature, allowed algorithm, issuer, audience, expiration, and any application-specific rules on the server.

You can use a browser-based developer tool to decode a harmless local test token, or decode the two non-signature segments in your own environment. Do not paste live access tokens, refresh tokens, session credentials, API keys, or tokens containing sensitive personal data into an online tool. Treat a bearer token as a credential even when its payload is readable.

Checklist by scenario

When the API returns 401 Unauthorized

1. Confirm the header format. Check that the request sends the token in the expected header, commonly Authorization: Bearer <token>. Look for a missing prefix, duplicated prefix, quotation marks, or whitespace introduced by string handling.
2. Check that the token has three segments. A signed JWT normally has two dots. A missing segment, line break, URL-decoding error, or truncated cookie can make the token unreadable.
3. Inspect expiration. The exp claim is normally represented as a numeric timestamp. Compare it with the server's current time, allowing for a small clock difference where appropriate. A token that decoded correctly can still be rejected because it has expired.
4. Check not-before restrictions. If the token includes nbf, the server may reject it until that time. This often points to clock skew, an incorrectly configured environment, or a token issued with a future activation time.
5. Compare issuer and audience. The iss claim should match the identity provider or issuer configured by the API. The aud claim should identify the intended API or resource. A token issued for one service is not automatically valid for another.

When the API returns 403 Forbidden

1. Separate authentication from authorization. A 403 response can mean the token was accepted but the caller lacks a required permission, role, scope, tenant, or resource-level entitlement.
2. Inspect permission claims. Look for the claim names your application actually uses, such as scope, roles, or a custom permission claim. Do not assume that a claim with a familiar name is interpreted automatically by your framework.
3. Check the requested resource. A valid token may still be blocked from a particular record, organization, route, or HTTP method. Compare the failing request with one that succeeds.
4. Review server-side authorization logs. Avoid returning detailed authorization reasons to untrusted clients. Record enough structured context on the server to identify which policy check failed.

When a token decodes but validation fails

1. Verify the signing algorithm. The server should allow only the algorithms it explicitly expects. The algorithm named in the token header should not be trusted as permission to select an arbitrary verification method.
2. Check the key or key set. A rotated signing key, wrong environment variable, incorrect key identifier, or stale public-key cache can cause a signature mismatch.
3. Confirm the token source. Make sure a development token is not being sent to staging or production, and that the client is not mixing tokens from different identity providers.
4. Compare raw values carefully. Base64url encoding, padding, Unicode handling, and accidental transformations can change the signed input. Log safe metadata and token fingerprints rather than full secrets.

When a frontend appears logged in but requests fail

1. Inspect the network request, not just the user interface state.
2. Check whether the client attaches the current access token to every protected request.
3. Look for a race where a request starts before token refresh completes.
4. Confirm that the API and browser application agree on cookie settings, cross-origin behavior, and the authentication transport.
5. Make sure a failed refresh clears or replaces the old token instead of retrying indefinitely.

What to double-check

Decode versus verify: Anyone who possesses a JWT can usually read its header and payload. That does not make the claims trustworthy. The API must verify the signature before using claims for access decisions.

Time claims: Check iat (issued at), exp (expiration), and nbf (not before) together. Confirm whether your libraries expect seconds or another unit, and verify that clocks are synchronized across the identity provider, API, containers, and host machines.

Claim meaning: Claims are data, not a universal contract. A role may be a string, array, or namespaced value depending on the issuer. Confirm the exact schema and mapping used by your application before changing permissions.

Environment configuration: Compare issuer URLs, audience values, key identifiers, discovery endpoints, and secrets across local, test, staging, and production environments. Configuration drift is a frequent source of authentication errors.

Logging: Do not log complete Authorization headers or raw refresh tokens. Prefer request IDs, token hashes or fingerprints, issuer, key ID, subject identifiers that are safe for your environment, and validation error categories. Redact sensitive fields before forwarding logs to a shared system.

Transport and storage: Use HTTPS for token transmission. Review where browser applications store tokens and whether that choice matches your threat model. A decoder cannot compensate for token exposure through logs, URLs, screenshots, browser storage, or copied support tickets.

For APIs that support search or other data-heavy workflows, authentication failures can be confused with application failures. Pair token checks with request tracing and API error monitoring; the workflow described in How to Monitor Search API Errors and Slow Queries is useful when a protected endpoint also has latency or query problems.

Common mistakes

• Assuming an online decode is a security check. It only exposes readable fields. Always validate on the server.
• Using the payload to authorize a request on the client. Frontend checks can improve user experience, but the API must enforce permissions independently.
• Trusting every claim from every issuer. Validate the issuer, audience, signature, algorithm, and expected claim shape.
• Ignoring key rotation. Verification code should handle the configured key set and key identifiers according to the identity provider's documented process.
• Testing with a copied production token. Use short-lived, least-privileged test credentials or local fixtures with fictional values.
• Refreshing on every 401 without a limit. A client can create a retry loop that hides the original problem and increases load. Coordinate refresh requests and stop after a bounded retry.
• Returning detailed validation errors to clients. “Token invalid” is usually safer externally than revealing whether a user, issuer, audience, or key check failed.
• Forgetting deployment configuration. A correct local setup can fail after deployment because environment variables, clock settings, callback URLs, or public-key access differ.

When to revisit

Return to this checklist whenever an authentication flow changes, not only when a request starts failing. Revisit it after switching identity providers, adding an API audience, changing token storage, enabling refresh-token rotation, modifying role or scope mappings, or introducing a new frontend or backend environment.

Use it during deployment reviews and before planned workflow changes. Confirm that test credentials are isolated, secrets are not present in logs, validation rules are covered by automated tests, and monitoring can distinguish expired tokens, invalid signatures, missing permissions, and unrelated application errors.

When a failure occurs, capture the endpoint, HTTP method, environment, request ID, response status, and safe validation category. Then work through the scenario that matches the symptom: header and structure for 401 errors, permissions and resource policy for 403 errors, and algorithm, key, issuer, and audience checks for signature or configuration failures. Decode only a sanitized token or local fixture, verify the result on the server, and document the final cause so the next investigation starts with evidence rather than guesswork.