A JWT decoder can quickly reveal why an API request is failing, but decoding is only the first step. This guide explains how to inspect JWT headers and claims, check expiration and audience values, verify signatures safely, and troubleshoot authentication without exposing production credentials.
Overview
JSON Web Tokens, usually called JWTs, are compact strings commonly used to carry authentication and authorization data between a client and an API. A token normally has three dot-separated parts: a header, a payload, and a signature.
The header describes the token format and signing method. The payload contains claims, such as a subject identifier, issuer, audience, issued-at time, or expiration time. The signature helps a receiving service determine whether the header and payload were signed with a trusted key and have not been changed.
A JWT decoder reads the header and payload so you can inspect their contents. It does not automatically prove that the token is authentic. This distinction is central to safe JWT debugging:
- Decoding converts the header and payload from Base64URL-encoded text into readable JSON.
- Validation checks whether the structure, data types, and required claims are acceptable.
- Verification checks the signature with the correct trusted key and algorithm.
Anyone who obtains a JWT can usually decode its header and payload. Do not treat encoded claims as secret, and do not assume that readable claims are trustworthy until the signature and relevant validation rules have been checked.
Core framework
1. Inspect the token structure
Start by confirming that the token has three non-empty segments separated by periods. A normal JWT resembles header.payload.signature. The first two segments use Base64URL encoding, which is similar to Base64 but uses URL-safe characters and may omit padding.
When using an online JWT debugger or another browser-based developer tool, work with a deliberately redacted or locally generated token whenever possible. A decoder should be used to understand a token’s contents, not as a place to store credentials.
2. Read the header
Pay attention to the alg and typ fields. The algorithm indicates how the signature was produced, while typ may identify the object as a JWT. The header can also contain a key identifier, often represented as kid, which helps a service select a verification key.
The header is an input to verification, not an authority. Server-side code should use an explicitly configured set of permitted algorithms and trusted keys rather than accepting any algorithm named by an untrusted token.
3. Inspect claims and their types
Common registered claims include:
iss: the issuer that created the token.sub: the subject or principal associated with the token.aud: the intended audience, such as a particular API.exp: the expiration time, represented as a numeric date.nbf: the time before which the token should not be accepted.iat: the time at which the token was issued.jti: an identifier that may support replay tracking or revocation workflows.
Claim names and application-specific fields vary by identity provider and API. Check whether values have the expected type. For example, an audience may be a string or an array, depending on the implementation, while time-based claims are generally numeric dates rather than formatted date strings.
4. Verify the signature and context
Signature verification requires more than copying a token into a decoder. Your application needs the correct trusted key, an allowed algorithm, and rules for claims such as issuer, audience, expiration, and not-before time. It should also account for reasonable clock differences without accepting tokens indefinitely.
Use the JWT library recommended for your language and identity provider, and follow its verification API rather than manually rebuilding cryptographic operations. A successful signature check shows that the token was signed by a holder of the corresponding key and was not modified; it does not by itself guarantee that the token is intended for your service or user.
Practical examples
Diagnosing an expired-token response
If an API returns an authentication error, decode the payload and inspect exp, iat, and nbf. Convert numeric dates to a readable time and compare them with the server’s clock, not only the browser’s clock. An expired access token may indicate a normal refresh flow, while a future nbf value can point to clock skew or an incorrectly issued token.
Do not fix an expiration problem by simply removing the claim or extending it in the client. The signature would no longer match, and a properly configured server should reject the modified token.
Diagnosing an audience or issuer mismatch
A token can be correctly signed and still be wrong for the API receiving it. Compare aud with the API’s configured audience and iss with the expected issuer URL. Check for differences in hostnames, paths, capitalization, or whether a value is represented as a string versus an array.
Configuration errors are common when a development identity provider, tenant, realm, or client application is confused with its production counterpart. Record the expected values in the service configuration and compare them systematically rather than changing validation rules until the request succeeds.
Separating token issues from request issues
Inspect the complete request in a controlled development environment. Confirm that the authorization scheme is formatted correctly, that the token is not truncated by a proxy or shell, and that the request is reaching the intended host. A valid JWT placed in the wrong header, sent to the wrong API version, or omitted by a browser credential policy can look like a signature problem.
For related API payload work, a JSON formatter and validator can make nested claims easier to inspect. If the token is used as part of an OpenAPI-described service, compare the documented security scheme with the server’s actual authentication requirements using an OpenAPI and Swagger workflow.
Safe handling during debugging
Prefer a local JWT decoder for sensitive work. If you use an online tool, use a synthetic token or remove sensitive values and work only in an approved environment. Never paste private signing keys, client secrets, refresh tokens, or unredacted production access tokens into an untrusted page. After a token has been exposed, follow your organization’s incident and revocation procedures rather than assuming that deleting browser history resolves the risk.
Common mistakes
- Confusing decoding with verification: readable claims are not proof of authenticity.
- Trusting client-side claims for authorization: access decisions must be enforced by the server after verification.
- Ignoring the audience: a token issued for one service should not automatically be accepted by another.
- Accepting the token’s algorithm without restrictions: configure permitted algorithms and trusted key sources explicitly.
- Reading expiration times incorrectly: numeric date claims are not always expressed in milliseconds. Confirm the library and specification expectations before converting them.
- Logging complete tokens: request logs, error trackers, and screenshots can preserve bearer credentials longer than expected. Log a short fingerprint or request identifier instead.
- Editing a payload to test a theory: a changed payload invalidates the signature. Use a test issuer or locally generated fixture instead.
- Assuming every authentication failure is a JWT failure: also check headers, routing, TLS termination, proxy behavior, key rotation, and environment configuration.
Environment-specific authentication settings should be separated and reviewed carefully. A guide to environment variable managers for local development can help keep local credentials and configuration distinct from production values.
When to revisit
Revisit your JWT debugging process whenever the identity provider, API gateway, signing algorithm, key-rotation process, or authorization library changes. Also update your runbook when claim names, issuer URLs, audiences, token lifetimes, or refresh behavior change. These values are configuration inputs, not permanent assumptions.
Before changing application code, use this short checklist:
- Copy only a safe test token and confirm its three-part structure.
- Decode the header and payload locally or in an approved tool.
- Check
iss,aud,exp,nbf, and relevant application claims. - Confirm the server’s allowed algorithms and current trusted keys.
- Compare the authorization header, target host, environment, and clock.
- Reproduce the issue with a newly issued test token before changing validation rules.
- Remove tokens from logs, tickets, screenshots, and shell history after debugging.
A JWT decoder is a useful inspection tool, but reliable authentication troubleshooting combines decoding, strict verification, correct request handling, and disciplined secret management. Treat each token as potentially sensitive, verify it in the service that will authorize the request, and document the expected claims so the next investigation starts with known assumptions.
