JWT Debugger

Why Your JWT Debugger Output Might Not Match Your Server

When you inspect a token, you're often looking for the "why" behind a 401 Unauthorized error. Many developers paste a token into a web tool only to see a "Signature Verification Failed" message. This usually happens because of a mismatch between the expected algorithm—like HS256—and the secret key format. A jwt debugger provides the transparency needed to spot if your token is malformed or if the header indicates an algorithm your backend doesn't support. Because this tool handles all calculations locally, you can safely experiment with different keys without exposing your production secrets to the network.

How the JSON Web Token Verification Algorithm Works

The process of validating a token revolves around three distinct parts encoded in Base64URL. The header defines the algorithm, such as HMAC with SHA-256 (HS256) or RSA Signature with SHA-256 (RS256). The jwt parser takes these components and recalculates the signature using your provided secret or public key. If the calculated signature matches the third part of the token, the integrity is verified.

Mathematically, for symmetric algorithms like HS256, the signature is computed as:
$$Signature = HMAC\_SHA256(Base64URL(Header) + "." + Base64URL(Payload), Secret)$$
When you use a jwt decoder, it doesn't just display text; it performs this cryptographic dance behind the scenes to confirm the data hasn't been tampered with. If even one character in the payload is altered, the resulting hash will fail to match the signature, alerting you to data corruption or unauthorized modification.

Decoding and Parsing JSON Web Token Claims

The payload section contains claims—the "meat" of the token. A common pitfall is ignoring the exp (expiration) or nbf (not before) claims. A json web token can look perfectly valid in structure but fail validation because the timestamp has lapsed.

Configuring Your JWT Verification Settings

The tool offers different modes depending on whether you are analyzing an existing token or building a new one for testing.

• Algorithm Selector: Choose between symmetric (HS series) or asymmetric (RS/ES series) algorithms. This must match the alg field in your token header.
• HMAC Secret Key: Used for HS256, HS384, and HS512. If your backend uses a Base64 encoded string, ensure you toggle the "Secret is base64 encoded" checkbox, or the signature will fail to verify.
• Public Key Input: For RS/ES algorithms, you can paste the public key in PEM (SPKI) or JWK format. The parser automatically detects the format to perform the verification.

Walkthrough: Validating a Token Signature

Let's look at how to verify a token that is throwing a validation error. Suppose you have a token that appears expired according to your logs.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE4MTYyMzkwMjJ9.xXyZ123...

Header: {"alg": "HS256", "typ": "JWT"}
Payload: {"sub": "1234567890", "exp": 1816239022}
Status: Valid

If the tool shows "Signature Verification Failed," first check if your secret is exactly 256 bits for HS256. Using a key that is too short is a common mistake that causes silent failures in production environments.

Quick Reference: Input and Output Formats

The jwt parser expects the standard compact serialization format (three base64url strings separated by dots).

• Input: Paste the full compact JWT string. Do not include extra whitespace or line breaks, as these can corrupt the base64 decoding.
• Header/Payload Output: The tool outputs standard JSON. You can edit these fields directly if you are in "Encode" mode to generate a new, signed token for your own testing.
• Key Formats: Support for raw text secrets, base64-encoded strings, and PEM-formatted public keys (beginning with -----BEGIN PUBLIC KEY-----).

Common Pitfalls in JWT Verification

When using a jwt debugger, remember that the payload is only encoded, not encrypted. Anyone with the token can read the claims. Never store sensitive data like passwords or PII in the payload. Another common error is assuming the alg: none header is supported; current verification libraries will reject these as they provide zero security against tampering. Always ensure your server is configured to reject tokens that do not explicitly use a secure, expected algorithm.

Resolving Token Inspection Issues with the JWT Debugger