A JWT decoder can make authentication failures easier to diagnose, but decoding is only the first step. This guide shows how to inspect a token locally, understand its claims, distinguish readable data from verified data, and build a repeatable checklist for frontend and API debugging without exposing production credentials.
Overview
JSON Web Tokens (JWTs) are compact strings commonly used to carry identity and authorization information between an application and an API. A token usually has three Base64URL-encoded parts separated by periods:
- Header: metadata about the token, such as the signing algorithm and token type.
- Payload: claims describing the subject, issuer, audience, timestamps, scopes, or application-specific data.
- Signature: a cryptographic value used to verify that the signed content has not been altered.
A browser-based JWT decoder or local decoding script can reveal the header and payload quickly. It does not, by itself, prove that the token was issued by a trusted authority, that its signature is valid, or that its claims should be accepted by your API. Treat the decoded result as an inspection aid, not as an authorization decision.
For safe troubleshooting, use a non-production token or a deliberately redacted copy whenever possible. Do not paste access tokens, refresh tokens, session credentials, client secrets, or tokens containing personal information into an unfamiliar third-party JWT decoder. If a token has been exposed, follow your identity provider's process for revoking or replacing it.
What to track
Use a safe decode workflow
When you need to decode a JWT token, follow the same sequence each time:
- Capture the right request. In browser developer tools, open the Network panel and select the failed API request. Check whether the request contains an Authorization header, a cookie, or another authentication mechanism.
- Copy only what you need. Prefer a test token. Remove the
Bearerprefix before pasting a token into a decoder, and never copy an entire set of production logs into a tool. - Confirm the shape. A conventional signed JWT has two periods and three segments. A malformed value, an opaque session identifier, or an encrypted token may not display ordinary readable claims.
- Inspect the header and payload. Review the algorithm label, key identifier, issuer, audience, subject, timestamps, and permissions. Record the values that differ between a working and failing request.
- Verify separately. Use the API or an appropriate server-side library to validate the signature and application rules. A decoded payload alone is not evidence that the token is authentic.
If you want to inspect a token without sending it to a website, decoding can be done in a local development console. This example is for inspection only and does not verify a signature:
function decodeBase64Url(value) {
const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
const bytes = Uint8Array.from(atob(padded), character => character.charCodeAt(0));
return new TextDecoder().decode(bytes);
}
function decodeJwtForInspection(token) {
const parts = token.split('.');
if (parts.length !== 3) throw new Error('Expected three JWT segments');
return {
header: JSON.parse(decodeBase64Url(parts[0])),
payload: JSON.parse(decodeBase64Url(parts[1]))
};
}
console.log(decodeJwtForInspection(testToken));
This browser example uses atob to decode Base64URL data after converting URL-safe characters and restoring padding. It intentionally omits signature verification. For production authentication, use a maintained JWT or OpenID Connect library appropriate for your server and identity provider rather than implementing cryptographic validation yourself.
JWT structure reference
| Part | What to inspect | What it does not prove |
|---|---|---|
| Header | alg, typ, and sometimes kid | That the named algorithm is acceptable or that the key is trusted |
| Payload | Identity, timestamps, audience, issuer, and scopes | That any claim is accurate, current, or authorized |
| Signature | Whether the signed content can be validated with the expected key | That your application has applied every required authorization rule |
JWT claims explained
Claim names can vary by provider, but these registered or widely used claims are common starting points:
iss(issuer): identifies the system that issued the token. Compare it with the exact issuer configured for your API, including formatting and environment.sub(subject): identifies the user, service, or entity represented by the token. Do not assume it is an email address; many providers use an opaque identifier.aud(audience): identifies the intended recipient. An otherwise valid token may be rejected if your API is not among its intended audiences.exp(expiration time): indicates when the token should no longer be accepted. JWT numeric dates are generally represented as seconds since the Unix epoch, not JavaScript milliseconds.nbf(not before): indicates that the token should not be accepted before a specified time.iat(issued at): records when the token was issued. It helps identify stale, unexpectedly cached, or newly minted tokens.scopeor permissions claims: describe delegated access or roles. The exact format may be a space-delimited string, an array, or a provider-specific claim, so inspect the API's expected convention.
Cadence and checkpoints
JWT debugging is most effective when you compare tokens and requests systematically rather than decoding a token only after a failed login. Use these checkpoints during development and whenever an authentication integration changes.
At the start of an integration
Write down the expected issuer, audience, signing algorithms, token location, required scopes, and time-handling rules for each environment. Keep development, staging, and production configuration visibly separate. Confirm whether the frontend receives an access token, an ID token, or a session cookie; these credentials may have different intended uses.
During a failing request
Compare the request that succeeds with the request that fails. Track the HTTP status, API host, method, Authorization header format, token age, issuer, audience, and scopes. A 401 often points to missing, malformed, expired, or unverifiable credentials, while a 403 may indicate that authentication succeeded but the caller lacks the required permission. Treat those status meanings as a debugging direction, not a universal rule; an API can define its own error behavior.
Also check whether the browser is sending the request you think it is. Inspect preflight requests, cookies, redirects, proxy rewrites, and environment variables. The frontend API debugging checklist can help separate authentication problems from CORS, fetch, and network failures.
Monthly or quarterly maintenance
Review authentication configuration on a recurring schedule, especially for applications with multiple environments or several identity providers. Check whether issuer and audience values still match deployed configuration, whether key identifiers rotate as expected, whether SDK or library versions have changed, and whether test fixtures still cover expired, not-yet-valid, wrong-audience, and insufficient-scope tokens. Avoid recording live tokens in permanent test data.
How to interpret changes
Expiration failures are often timing problems rather than permission problems. Compare the token's exp, nbf, and iat values with the server's clock and the time at which the request was made. A small difference between client and server clocks can make a token appear expired or not yet valid at a boundary. Handle clock tolerance through the server library's documented configuration rather than adding a large, unexplained grace period.
If a token appears correct but the API rejects it, work through these distinctions:
- Decoding versus verification: anyone who receives a JWT can usually decode its header and payload. Only successful verification with the expected key establishes integrity.
- Verification versus authorization: a valid signature does not automatically grant access. The API must still check issuer, audience, expiry, scopes, roles, tenant boundaries, and resource ownership as applicable.
- Access token versus ID token: an identity token may describe a login event for a client, while an access token is intended for an API. Use each only for its documented purpose.
- Token versus transport: a valid token can fail to reach the API because a header was omitted, a cookie was blocked, a proxy removed it, or a redirect changed the request context.
Do not trust the alg value merely because it appears in the decoded header. The verifier should enforce an allowlist and select trusted keys and algorithms through server-side configuration. Likewise, do not use decoded client-side claims to hide privileged UI as a substitute for server authorization. Client-side checks can improve user experience, but the API must enforce access.
Debugging checklist
- Is the value a three-part JWT, and is it being copied without the
Bearerprefix? - Is the request going to the intended environment and API host?
- Are the issuer and audience exact matches for that API?
- Are
expandnbfbeing interpreted as seconds rather than milliseconds? - Is the server verifying the signature with a trusted key and permitted algorithm?
- Is the required scope or role present in the format the API expects?
- Could clock skew, caching, refresh logic, CORS, cookies, or a proxy be involved?
- Are logs exposing tokens or sensitive claims?
When to revisit
Revisit this JWT decoder workflow whenever authentication behavior changes, not only when a user reports a login failure. A quarterly review is a practical baseline for active projects; review sooner after changing an identity provider, API gateway, frontend authentication library, token lifetime, signing-key configuration, scope model, or deployment environment.
Make a short record of the expected issuer, audience, token location, claim names, verification library, and test cases. Update it when provider documentation or SDK behavior changes. Re-run the same safe checks after a browser, framework, or build-tool upgrade if authentication requests are assembled by frontend code.
For the next debugging session, start with a non-production token, decode locally when possible, compare the complete request with a known-good request, and verify the token on the server before changing application logic. That separation—read the claims, verify the signature, then evaluate authorization—keeps a JWT decoder useful without mistaking readable data for trusted identity.