A JWT decoder can show you what a token contains, but it cannot tell you whether the token is authentic. This checklist explains the difference between decoding and verification, how to inspect claims safely, and what to check when an API reports an expired token or invalid signature.
Overview
A JSON Web Token (JWT) is commonly represented as three dot-separated parts: a header, a payload, and a signature. The header and payload are JSON objects encoded with base64url. The signature is used to detect whether the signed content has been changed and, depending on the signing method, to establish that the signer controlled the relevant key.
Decoding is only a formatting operation. A JWT decoder can split the token and turn its header and payload into readable JSON. It does not prove who issued the token, whether the payload is current, or whether the signature is valid. Base64url encoding is not encryption, so you should assume that anyone who receives a JWT can read its non-encrypted claims.
Verification is a security operation. A verifier checks the signature using the expected algorithm and key, then evaluates the claims against the rules for the application. Those rules commonly include the expected issuer (iss), audience (aud), expiration time (exp), not-before time (nbf), and sometimes the issued-at time (iat). A token can be successfully decoded and still fail every meaningful authentication check.
Use an online JWT decoder only with deliberately non-sensitive data, such as a locally generated test token or a redacted example. Do not paste production access tokens, refresh tokens, session tokens, API keys, or personal information into a third-party tool. For live incidents, prefer a local decoder or a trusted development environment.
JWT claims at a glance
| Claim or field | What to inspect | Important limitation |
|---|---|---|
alg | The signature algorithm named by the token | Do not accept an algorithm solely because the token requests it; configure an explicit allowlist. |
kid | The key identifier used to select a verification key | It must resolve to a trusted key from the expected issuer, not an arbitrary location. |
iss | The principal that issued the token | Compare it with the exact issuer configured for the application. |
aud | The intended recipient or service | Check the expected audience and account for whether the value is a string or an array. |
exp | Expiration time as a numeric date | A token should not be accepted after this time, subject only to a narrowly defined clock-skew policy. |
nbf | Time before which the token must not be accepted | Server clock differences can make a newly issued token appear premature. |
sub | The subject represented by the token | Interpret its meaning according to the identity provider and your application. |
scope or roles | Permission-related values | Never treat their presence as proof that the token is genuine until verification succeeds. |
Checklist by scenario
When you need to inspect a token
- Obtain it safely. Copy a test token or a redacted sample. Keep the three segments intact, including punctuation and case.
- Check the shape. A signed JWT normally has three dot-separated segments. An unexpected number of segments may indicate a malformed value or a different JOSE format.
- Decode the header and payload. Review the JSON structure, the declared algorithm, the key identifier, and the time-related claims. A decoder is useful here, but its output is untrusted input.
- Record the expected context. Write down which identity provider, issuer, audience, environment, and token type the application expects. “It looks like our token” is not a verification rule.
- Remove secrets from logs. Log claim names, selected values, and error categories where possible, rather than the complete token.
When an API returns an invalid signature
- Confirm that the token was not truncated, wrapped incorrectly, or copied with an extra space.
- Compare the token's
algandkidwith the algorithms and signing keys configured by the service. - Check that the verifier is using the correct environment. A staging token and production key set should not be interchangeable.
- Check key availability and rotation timing. A key selected by
kidmay no longer be published, or the verifier may have stale key material. - Verify that the library receives the complete token and the expected key type. An asymmetric signing method requires the appropriate public key; a shared-secret method requires the intended secret.
- Review the library's verification error without exposing the token. Distinguish malformed input, unavailable keys, unsupported algorithms, and signature failure.
When an API returns an expired or not-yet-valid error
- Decode
exp,nbf, andiatas numeric dates and compare them with the server's current time, not only your laptop's clock. - Check the units. JWT time claims are generally expressed as seconds from the Unix epoch; an application that treats them as milliseconds can produce confusing results.
- Measure clock skew between the issuer, API, container, and host. If the application permits a leeway window, keep it explicit, small, and consistent.
- Confirm that the client is not reusing a cached token after its intended lifetime.
- Request a new token through the normal authentication flow rather than editing the payload. Changing a claim invalidates the signature.
When integrating a new identity provider
- Document the exact issuer and audience values for each environment.
- Identify which claim represents the user or service account and which claims carry permissions.
- Configure supported algorithms rather than accepting whatever the header announces.
- Use the provider's trusted key-discovery mechanism or an explicitly managed key set, with a plan for rotation and temporary key overlap.
- Test valid, expired, future-dated, wrong-audience, wrong-issuer, altered-payload, and unknown-key tokens.
What to double-check
Verification order matters. A typical server-side flow first parses the token, selects only a configured algorithm, obtains a trusted key, verifies the signature, and then validates the claims. Exact sequencing depends on the library, but parsing a claim must never be confused with accepting it.
The algorithm is configuration, not user input. The alg header helps describe how the token was produced, but an attacker controls the token presented to your application. Configure an allowlist appropriate to your system and reject unexpected algorithms. Do not solve an algorithm error by disabling signature verification.
The issuer and audience are different checks. The issuer identifies who created the token. The audience identifies the service or recipient for which it was created. A token from a trusted issuer may still be intended for a different API. Validate both where your architecture requires them.
Keys must come from a trust boundary. The kid value is a selector, not proof of identity. Resolve it against keys associated with the expected issuer and apply your key-rotation and caching rules. Avoid designs that let an untrusted token choose an arbitrary URL from which verification material is downloaded.
Access tokens and identity tokens may have different purposes. Claim names and conventions vary by provider and protocol profile. Use the token type your API is designed to receive, and document which claims your application actually relies on. Do not infer authorization solely from a familiar-looking field.
Decoding in a browser is not authentication. Frontend code can decode a token to display debugging information, but anything in the browser can be inspected or modified by the user. Authorization decisions belong on a trusted backend or resource server that verifies the token and applies its own access rules.
Common mistakes
- Calling a decoder a verifier. Readable JSON proves only that the segments can be parsed.
- Assuming signed means encrypted. A normal signed JWT does not hide its payload. Avoid putting secrets or unnecessary personal data in claims.
- Trusting
sub,role, oradminbefore verification. Any caller can construct a token-shaped string with those values. - Ignoring the audience. Acceptance by the right issuer does not automatically make a token appropriate for every service.
- Using a broad clock-skew allowance. A large tolerance can turn an expired or future-dated token into an accepted one. Fix clock synchronization and define leeway deliberately.
- Logging complete bearer tokens. Tokens in logs, screenshots, tickets, or chat transcripts can become credentials. Redact them and establish retention controls.
- Changing claims to repair a failing token. Any payload change alters the signed content. Obtain a correctly issued token instead.
- Testing only the happy path. Include invalid signatures, unknown key IDs, wrong audiences, expired tokens, malformed dates, and key-rotation cases in automated tests.
When to revisit
Revisit this checklist before integrating a new identity provider, adding an API audience, changing authentication libraries, or moving verification between local, staging, and production environments. It is also worth reviewing when a provider changes its claim conventions, signing algorithms, key-discovery endpoint, or rotation process.
During an incident, return to the scenario that matches the observed error: inspect safely, compare issuer and audience, check time units and clock skew, then investigate algorithm and key selection. Do not begin by editing the token or weakening verification.
As a practical maintenance step, keep a small authentication test matrix beside the service configuration. Record the expected issuer, audiences, allowed algorithms, key source, required claims, clock policy, and redaction rules. Re-run it whenever workflows or tools change. A JWT decoder remains useful for understanding a payload, but only a properly configured verifier should determine whether your application accepts it.