Read the Claims Without Confusing Decoding With Trust

A compact JSON Web Token usually contains three dot-separated segments: a JOSE header, a claims payload, and a signature. The first two segments are Base64URL-encoded JSON, not encrypted text. This decoder turns those segments into formatted objects, displays the signature material, interprets common NumericDate claims, and can verify one specific signature algorithm: HS256 with a supplied text secret.

Being able to read a token does not establish that it came from a trusted issuer. Anyone can construct header and payload JSON and encode it. Trust begins only after an application verifies the signature with the expected algorithm and key, then validates claims such as issuer, audience, expiration, and authorization scope.

Anatomy of the Compact Token

The encoded form has this shape:

base64url(header).base64url(payload).base64url(signature)

A typical header might decode to:

{
  "alg": "HS256",
  "typ": "JWT"
}

The alg value announces the signing algorithm. The typ field is often JWT, although consumers must not depend on appearance alone. A payload might contain registered claims and application data:

{
  "sub": "user-1842",
  "iss": "https://auth.example.com",
  "aud": "billing-api",
  "iat": 1786968000,
  "exp": 1786971600,
  "scope": "invoices:read"
}

The signature covers the original encoded header and payload joined by a dot. Changing even one claim requires a new valid signature. The signature segment is displayed as encoded material; it is not decoded into meaningful JSON.

Using the Decoder

Paste only the compact token into Encoded JWT Token, without Bearer , quotation marks, or surrounding JSON. The page updates immediately. A structurally compatible token produces separate Header and Payload panels with formatted JSON and copy controls. The token itself can also be copied or cleared.

Review the header before relying on any verification result. If alg is HS256, the Signature Details panel offers a field for the HMAC secret. Enter the exact secret bytes as text. After a brief debounce, the tool computes HMAC-SHA-256 over encodedHeader.encodedPayload, converts the result to unpadded Base64URL, and compares it with the supplied signature.

A successful message means the token signature matches that exact entered text key under HS256. An invalid message can mean the secret is wrong, the token changed, the secret was interpreted differently, or the producer did not actually use the expected algorithm and bytes.

Timestamps and Expiration

The decoder recognizes numeric exp, iat, and nbf payload fields. JWT NumericDate values are seconds since the Unix epoch, unlike JavaScript timestamps, which are commonly milliseconds. The page multiplies each value by 1,000 and shows a localized date and time.

iat is the time the token was issued.
nbf states that the token must not be accepted before that time.
exp states that it must not be accepted at or after expiration under normal validation policy.

The interface marks an exp date as Expired when it is earlier than the browser’s current clock. It does not mark a future nbf as unusable, enforce clock skew, or decide whether iat is plausible. Those decisions remain with the token consumer.

If a timestamp is a string rather than a JSON number, it is not included in the timestamp cards. If a producer uses milliseconds by mistake, the displayed date will be far in the future. That is a useful diagnostic sign, but the decoder does not automatically correct units.

Debugging an API Authentication Failure

When an API returns 401, capture the token from a safe development environment and paste the compact value. Work through the result in this order:

Confirm there are exactly three segments and that header and payload parse as JSON.
Check alg against the algorithm your service is configured to allow.
Inspect iss and aud for exact expected values, including case and URI formatting.
Read exp, iat, and nbf in the displayed local time, while accounting for server clock and configured tolerance.
Inspect sub, roles, scope, tenant, or other application claims required by the endpoint.
For a development HS256 token, verify with the exact secret if policy permits entering it.

This sequence separates token shape, claim policy, and cryptographic verification. A valid HS256 signature does not guarantee the audience is correct, and an unexpired payload does not compensate for a bad signature.

Common Decode Errors

Invalid JWT structure appears when trimming and splitting on . does not yield exactly three segments. Remove the Bearer prefix, surrounding quotes, trailing punctuation, or line wrapping. An encrypted JWE commonly has five segments and is not supported by this JWT decoder.

Failed to parse JWT Header JSON means the first segment could not be converted from Base64URL to valid UTF-8 JSON. Failed to parse JWT Payload JSON means the same for the second segment. Possible causes include truncated copy/paste, a non-JWT compact format, malformed Base64URL, or a segment that decodes to text but not a JSON object.

The decoder normalizes - to +, _ to /, and restores padding before browser Base64 decoding. It then uses TextDecoder for UTF-8. Standard Base64 input may sometimes look similar, but JWT producers should use the URL-safe form prescribed by JOSE.

If formatted JSON appears but values look wrong, compare the raw token from its source. Browser extensions, log redaction, wrapping, or templating can replace characters. Never “repair” the payload and continue using the original signature; changing encoded content invalidates cryptographic integrity.

HS256 Verification Details

HS256 is a symmetric algorithm: issuer and verifier share the same secret. The secret must have sufficient entropy and be handled like a password or private key. A human-readable production secret is often weaker than a randomly generated key.

This field interprets entered characters through TextEncoder, producing UTF-8 bytes. If another system stores the key as Base64 text, hexadecimal, or a binary key, entering its displayed representation is not the same as decoding that representation into key bytes. For example, a configuration value documented as “Base64-encoded secret” usually needs Base64 decoding before HMAC use; this interface has no key-format selector.

Verification is supported only when the decoded header’s alg is exactly HS256. Tokens using RS256, ES256, PS256, EdDSA, or other algorithms display an explanatory limitation instead of accepting a public key. Use your application’s JOSE library and trusted key set for those algorithms.

Claims the Tool Displays but Does Not Validate

Formatted payload output makes every claim visible, including custom claims, but visibility is not enforcement. The tool does not check:

iss against an issuer allowlist;
aud against a required audience, whether string or array;
jti against revocation or replay state;
required scopes, roles, tenant IDs, or subject format;
maximum token age based on iat;
critical JOSE headers or key identifiers;
whether alg: none is prohibited by the consumer.

These checks are application-specific. Production code should configure an established JWT library with allowed algorithms and expected claims rather than decode JSON and manually trust fields.

Handling Tokens Safely

JWT payloads frequently contain user identifiers, email addresses, tenant information, and authorization data. Bearer tokens can grant access to whoever possesses them until expiration or revocation. Use synthetic or already-revoked examples for debugging whenever possible.

The component performs decoding and HS256 calculation in the browser. Nevertheless, exposing a live token or secret on screen, in clipboard history, in a recording, or to browser extensions can create risk. Do not paste production signing secrets into an unapproved environment. Clear the fields when finished.

The Copy Header and Copy Payload actions produce pretty-printed JSON, which is convenient for a ticket but can disclose claims. Redact identifiers and never include the original bearer token unless the recipient and channel are authorized.

Decoder Limitations

This tool handles compact, three-part tokens whose header and payload are JSON. It does not decrypt JWE, fetch JSON Web Key Sets, select a key by kid, validate X.509 chains, or contact an issuer. It does not preserve a server-side audit trail or model token revocation.

Localized timestamp output follows the browser’s locale and timezone, so it may differ from UTC logs. Compare the raw epoch value when diagnosing cross-timezone incidents. Expiration marking uses the client clock, which may differ from the validating server.

Finally, syntactic decoding is permissive by design. Security-sensitive acceptance belongs in backend or trusted client code using a maintained JOSE implementation and explicit policy.

JWT Decoder FAQ

Can a JWT be decoded without a secret?

Yes. Header and payload are encoded, not encrypted. A secret or public key is needed to verify a signature, not to read those segments.

Why does my token have five parts?

It is likely a JWE compact serialization, which includes protected header, encrypted key, IV, ciphertext, and authentication tag. This tool expects a three-part signed JWT/JWS.

Why is an HS256 signature invalid with the documented secret?

Check whether the documented value is raw text, Base64, hexadecimal, or a reference to another secret. This field uses the UTF-8 bytes of exactly what you type.

Can the tool verify RS256 with a public key?

No. Interactive verification is limited to HS256. Use a JOSE library configured with the issuer’s trusted RSA key or JWKS.

Does “Signature Verified Successfully” mean the token should be accepted?

No. It proves one HS256 comparison. The application must still validate algorithm policy, expiration, not-before time, issuer, audience, and authorization claims.

Why is the expiration date unexpectedly far in the future?

The producer may have used milliseconds rather than NumericDate seconds. Compare the raw exp value with the JWT specification and token-issuing code.

Does the decoder support Unicode claims?

Yes, when the Base64URL payload contains valid UTF-8 JSON. The component decodes segment bytes with TextDecoder before parsing JSON.

JWT Decoder