Understanding JSON Web Tokens: Structure, Verification, and Offline Debugging

A JSON Web Token (JWT) is an open, industry-standard (RFC 7519) compact and self-contained mechanism for securely transmitting digitally signed information between parties as a JSON object. Used predominantly for stateless authentication and authorization headers, a JWT consists of three Base64URL-encoded segments separated by periods (.): a header defining the algorithm and token type, a payload containing identity claims and expiration timestamps, and a cryptographic signature created using symmetric secrets (such as HMAC SHA-256) or asymmetric keypairs (such as RSA or ECDSA). Because JWTs are encoded rather than encrypted by default, their payload claims remain visible to anyone with access to the raw string. Ensuring proper token integrity requires strict cryptographic validation on every request, verifying both token expiration and signature consistency against your application's public key or secret.

[!TIP] Need to verify or inspect your tokens now? Try our free, local JWT Editor and Signature Decoder to parse, inspect, and sign payloads completely offline without server telemetry.

---

Anatomy of a JWT: Breaking Down the Three Segments

A raw JWT string looks like three alphanumeric blocks joined by dots: header.payload.signature. Decoding each segment reveals standard JSON objects structured according to identity standards.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiYWRtaW4iOnRydWUsImlhdCI6MTczOTY2NDAwMH0.d7...

1. Header (JOSE Header)

The header contains metadata that instructs verification libraries on how to process the token. It typically specifies the algorithm (alg) and the token type (typ):

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

Common algorithms include HS256 (HMAC with SHA-256), RS256 (RSA signature with SHA-256), and ES256 (ECDSA using the P-256 curve).

2. Payload (Claims Set)

The payload contains the transmission claims. Standard Registered Claims include iss (issuer), sub (subject), aud (audience), exp (expiration time), and iat (issued at). Custom claims can also hold user roles or tenant IDs:

{
  "sub": "usr_99a81b7e",
  "name": "Dev User",
  "role": "admin",
  "iat": 1739664000,
  "exp": 1739667600
}

3. Signature

The signature validates that the token was not tampered with during transit. It is calculated by taking the Base64URL-encoded header and payload, concatenating them with a period, and running them through the chosen hashing algorithm alongside a secret key:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  your-256-bit-secret
)

---

Core Security Pitfalls to Avoid

Implementing JWTs requires rigorous handling on both client and server layers. Overlooking basic token security can lead to critical authorization bypass vulnerabilities.

• Never Store Sensitive Data in Claims: JWT payloads are Base64URL encoded, not encrypted. Passwords, API tokens, and PII should never be stored within standard JWT payloads.
• Reject the none Algorithm: Malicious actors may rewrite the header alg field to none to bypass signature checks. Always enforce allowed algorithms explicitly in your backend verifier.
• Validate Timestamps Strictly: Enforce the exp (expiration), nbf (not before), and iat (issued at) claims to minimize the attack surface of intercepted tokens.
• Safeguard Symmetric Secrets: Use high-entropy keys for HMAC algorithms. Short or common dictionary words are easily broken via brute-force offline cracking tools.

---

How to use this offline in your browser

Many online token visualizers upload pasted tokens and signing keys to third-party servers, posing serious security and compliance risks for staging and production environments. Pasting private production tokens or HMAC secrets into web tools that store server logs can lead to credential leakage.

By utilizing Web Crypto APIs and browser-native JavaScript engines, you can debug and verify tokens completely on the client side:

1. Client-Side Decoding: The browser natively decodes Base64URL strings using standard JavaScript encoding primitives without sending API requests.
2. Local Key Verification: Cryptographic checks using RSA, ECDSA, or HMAC are executed inside your browser sandbox via window.crypto.subtle.
3. Air-Gapped Operation: Once the web application asset bundle is loaded, you can disconnect your network connection entirely. Parsing, claims formatting, and signature verification function identically without an internet connection.
4. Zero Server Roundtrips: Data isolation guarantees that your authentication headers, authorization scopes, and internal user identifiers never leave your local machine.

---

Conclusion

JWTs provide a standardized format for exchanging claims across decoupled distributed architectures. However, their security relies on strict validation routines, careful claim management, and safe debugging workflows that keep sensitive credentials private.