JWT Token Debugging: A Complete Guide to Decoding and Validating

JSON Web Tokens (JWTs) are the backbone of modern authentication. They carry user identity, permissions, and expiration data in a compact, self-contained format. But when something goes wrong — an unexpected 401, a missing claim, a mysterious expiration error — you need to crack open the token and inspect its contents. That is where a JWT decoder becomes an essential debugging tool.

This guide covers everything you need to know about JWT token debug workflows: the structure of a JWT, how to decode each section, what to look for when things break, and security pitfalls to avoid.

What Is a JWT?

A JWT (pronounced "jot") is a compact, URL-safe token format defined in RFC 7519. It consists of three Base64URL-encoded parts separated by dots:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkphbmsiLCJpYXQiOjE2OTAwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
│_________header__________│_________________payload_________________│__________________signature__________________│

Each part serves a distinct purpose:

Decoding the Header

The header is a Base64URL-encoded JSON object. Decoding the first segment:

// Input:  eyJhbGciOiJIUzI1NiJ9
// Decode:
{
  "alg": "HS256",
  "typ": "JWT"
}

The alg field tells the verifier which algorithm was used to sign the token. Common values:

• HS256 — HMAC with SHA-256 (symmetric, shared secret)
• RS256 — RSA with SHA-256 (asymmetric, public/private key pair)
• ES256 — ECDSA with SHA-256 (asymmetric, shorter keys)
• none — No signature (dangerous — see security section below)

Decoding the Payload

The payload contains the claims — the actual data the token carries. There are three types of claims:

Registered Claims (Standard)

These are predefined in the JWT specification and have specific meanings:

{
  "sub": "1234567890",    // Subject (user ID)
  "name": "Jan Kowalski", // Custom claim
  "iat": 1690000000,      // Issued At (Unix timestamp)
  "exp": 1690003600,      // Expiration (Unix timestamp)
  "iss": "auth.example.com", // Issuer
  "aud": "api.example.com"   // Audience
}

Public and Private Claims

Public claims use collision-resistant names (URIs or IANA-registered names). Private claims are custom fields agreed upon between the issuer and consumer — like role, org_id, or permissions.

A JWT decoder reveals the payload in plain text. Never put sensitive data — passwords, credit card numbers, personal details — in a JWT payload. The payload is Base64URL-encoded, not encrypted.

Understanding the Signature

The signature ensures the token has not been tampered with. For HS256, it is computed as:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

The signature does not encrypt the payload. It only guarantees integrity — confirming that the header and payload were not modified after the token was issued. Without the secret key, an attacker cannot produce a valid signature, but they can read the payload freely.

Common JWT Debugging Scenarios

Token Expired (exp claim)

The most common JWT error. Decode the token and check the exp claim. Convert the Unix timestamp to a human-readable date to see exactly when the token expired. A common mistake is timezone mismatch — the server and client might interpret timestamps differently.

Wrong Audience (aud claim)

If your API rejects a token with "invalid audience," the aud claim does not match what the server expects. Decode the token and compare the aud value against the server's configuration.

Algorithm Mismatch

The header's alg field must match the server's expected algorithm. If the token uses RS256 but the server verifies with an HMAC secret, verification will fail — even if the data is correct.

Malformed Token

A JWT must have exactly three Base64URL segments separated by dots. If a JWT decoder reports "malformed token," check for:

• Missing dots or extra whitespace
• Truncated tokens from copy-paste errors
• Standard Base64 characters (+, /) where Base64URL (-, _) is expected

Security Pitfalls to Watch For

The "none" Algorithm Attack

Some JWT libraries accept tokens with "alg": "none" and skip signature verification entirely. An attacker can forge a token with any payload and a null signature. Always whitelist allowed algorithms on the server side — never trust the token's own alg claim.

Algorithm Confusion (RS256 to HS256)

If a server expects RS256 (asymmetric) but the library also accepts HS256 (symmetric), an attacker can sign a token with the server's public key as the HMAC secret. This is a well-documented attack — always enforce the expected algorithm explicitly.

Sensitive Data in Payload

The JWT payload is readable by anyone. It is Base64URL-encoded, not encrypted. Never include passwords, API keys, or personally identifiable information that should remain private.

How to Use the DevKitDock JWT Decoder

Our JWT Decoder makes debugging tokens fast and safe:

1. Paste your JWT token into the input field
2. The tool automatically splits the three parts and decodes header and payload
3. Registered claims like exp, iat, and nbf are displayed as human-readable dates
4. The signature section is shown separately for inspection
5. Everything runs client-side — your token is never sent to a server

This is especially useful during development when tokens come from third-party OAuth providers, API gateways, or microservice authentication flows.