JWT authentication failures are often caused by a small mismatch between what a client sends, what an identity provider signs, and what an API expects. This guide provides a repeatable way to decode a JWT, validate its claims and signature, isolate common errors, and share useful debugging evidence without exposing credentials or production secrets.
Overview
A JSON Web Token (JWT) is a compact string commonly used to carry claims between a client and an API. A signed JWT usually has three dot-separated parts: a header, a payload, and a signature.
- Header: Identifies the token type and signing algorithm, commonly through fields such as
typandalg. - Payload: Contains claims such as
iss(issuer),sub(subject),aud(audience),exp(expiration time), andnbf(not before). - Signature: Allows a verifier to check that the signed content has not been changed and that it was produced by a trusted signing process.
Decoding is not the same as validating. A JWT decoder can display the header and payload, but readable claims do not prove that a token is authentic, current, or authorized for a particular API. Treat every decoded value as untrusted until the server has verified the signature and applied its claim rules.
JWTs are typically base64url-encoded rather than encrypted. Anyone who obtains a token may be able to read its payload, so access tokens should not contain passwords, private keys, or other secrets. The most useful debugging process separates three questions: can the client send the token correctly, can the server cryptographically verify it, and does the verified token satisfy the API's authorization requirements?
Step-by-step workflow
1. Capture the request safely
Start with the exact failing request and record the method, URL, status code, response body, and relevant request headers. Confirm that the token is sent in the expected format, usually an HTTP header such as Authorization: Bearer <token>. Watch for extra quotation marks, line breaks, URL encoding, an omitted Bearer prefix, or a token copied from the wrong environment.
Do not paste a live production token into a ticket, chat room, browser history, or third-party debugging service. If a token must be shared for diagnosis, use a deliberately generated test token or redact the sensitive value and preserve only safe metadata such as the number of segments and the relevant error category.
2. Check the token shape
A signed JWT normally contains two dots and three segments. An absent segment, an unexpected prefix, or a value that is not valid base64url suggests a formatting or transport problem. This check is only a first filter; a correctly shaped string can still be expired, forged, issued for another service, or signed with an unexpected key.
Use a trusted local utility or a carefully selected browser-based JWT decoder to inspect a non-sensitive token. A decoder is useful for quickly reading claims and comparing a working request with a failing request. It does not replace the API's verification library or identity-provider configuration.
3. Decode the header and payload
Compare the failing token with a known-good token from the same environment. Look for differences in:
iss: Is the issuer the one configured for this API?aud: Is the token intended for this API rather than a different client or resource?sub: Does the subject identify the expected user, service, or account?scopeorroles: Does the token carry the permission the endpoint checks?expandnbf: Is the token currently valid according to its time claims?kid: Does the key identifier correspond to a key available to the verifier?
Time claims are commonly represented as numeric timestamps. Convert them consistently and compare them with the server's clock, not only the developer workstation's clock.
4. Validate the signature and algorithm
The resource server should verify the signature using a trusted key and an explicitly configured set of algorithms. Do not select verification behavior solely from untrusted token input. An algorithm mismatch may occur when the issuer signs with one algorithm but the API is configured for another, when a public key was rotated, or when the service is reading the wrong issuer's key set.
Check the configured issuer, discovery or key endpoint, expected algorithm, and key identifier. In a multi-environment system, confirm that development, staging, and production are not mixing issuers or signing keys. A decoded kid is a clue, not proof that the corresponding key is trustworthy.
5. Validate claims and authorization separately
After signature verification succeeds, validate the claims required by the application. An API may reject a token because its issuer or audience is wrong even when the signature is valid. It may also reject a valid identity because the endpoint requires a scope or role that the token does not contain.
Keep authentication and authorization errors distinct in logs and responses. “The token could not be verified” points toward transport, key, issuer, or algorithm troubleshooting. “The token is valid but not permitted” points toward scopes, roles, resource ownership, or endpoint policy.
6. Test expiration and refresh behavior
If the token is expired, determine whether the client should obtain a new access token through its refresh workflow. Avoid treating every 401 response as a reason to retry indefinitely. A client should have bounded retries and should clear or reauthenticate when refresh fails.
Also inspect clock skew. A small difference between the identity provider's clock and the API host can make nbf or exp appear invalid near a boundary. Configure a narrowly scoped tolerance only when the platform and security model justify it; a broad tolerance extends the effective lifetime of tokens.
Tools and handoffs
Use the least powerful tool that answers the question:
- JWT decoder: Inspect the structure and claims of a synthetic or non-sensitive token.
- API client or command-line request: Reproduce the request with a controlled method, URL, header set, and test credential.
- Server logs: Identify whether failure occurred during parsing, signature verification, claim validation, or authorization. Log error categories and request identifiers, not raw tokens.
- Identity-provider console or configuration: Compare issuer, audience, scopes, key identifiers, and token lifetime settings across environments.
- Tracing and request correlation: Follow a request from gateway to application when multiple services can reject or transform the authorization header.
For Node.js services, consistent structured logging can make authentication failures easier to connect with downstream API behavior. The Mongoose logging best practices guide covers useful patterns for API debugging and incident response. If authentication failures appear alongside latency or dependency errors, distributed tracing can help separate token problems from service-to-service failures; see what to trace with OpenTelemetry for Node.js and Mongoose.
When handing an issue to another developer, include the environment, endpoint, timestamp, correlation ID, status code, sanitized claim summary, and the validation stage that failed. This is more actionable than attaching a raw token or saying only that “JWT auth is broken.”
Quality checks
Before closing a JWT debugging task, run through this checklist:
- The token was tested without exposing a live credential.
- The request contains the expected authorization scheme and exactly one token.
- The token has the expected number of segments and can be decoded without mutation.
- The issuer, audience, subject, scopes, roles, and time claims match the intended environment and endpoint.
- The server verifies the signature with a trusted key and an allowed algorithm.
- Key rotation and the token's
kidhave been considered. - Authentication failures are distinguished from authorization failures.
- Refresh behavior has bounded retries and does not create a request loop.
- Logs and traces contain correlation data but not authorization headers, full tokens, or sensitive payload values.
- A regression test covers the failure that was fixed.
Also test negative cases deliberately: an expired token, an incorrect audience, a missing scope, a malformed token, and a token signed by an untrusted key. These cases help confirm that the verifier rejects invalid input rather than merely accepting the happy path.
When to revisit
Return to this workflow whenever an identity provider, API gateway, authentication library, signing algorithm, key-rotation process, or environment configuration changes. Revisit it after changing token lifetimes, refresh-token handling, clock synchronization, scopes, roles, or service-to-service authentication.
Make the guide part of the team's operational documentation. Keep a sanitized example token, a known-good request, expected claim requirements, and the location of relevant logs or traces. Review the example whenever the API contract changes so that developers do not debug against outdated audiences or scopes.
For a practical next step, choose one protected endpoint and document its complete verification path: where the token originates, which client sends it, which gateway or service first receives it, which issuer and audience are expected, and how authorization is decided. Then add automated tests for one failure at each stage. This turns a browser-based decode or ad hoc API check into a repeatable developer utility workflow that remains useful as the system evolves.
