How to Decode and Inspect JSON Web Tokens (JWT): Structure, Base64URL, and Security Traps

JSON Web Tokens (RFC 7519) are compact, URL-safe tokens used widely for authentication and stateless session propagation. While inspecting a JWT is trivial once you understand its structure, treating decoded claims as trusted data without cryptographic verification is one of the most common security vulnerabilities in web architecture.

The Anatomy of a JSON Web Token Three Dot Separated Segments

A standard JWT is a single string composed of three distinct segments separated by periods (.):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkphbmUgRG9lIiwiYWRtaW4iOnRydWUsImV4cCI6MTc5ODc2MTYwMH0.u2P_f6fK4Z1g0X4PzH-4z7cK7p9n7Z6n5d8b7b2x3a4
|___________ HEADER ___________| |________________ PAYLOAD ________________| |_______________ SIGNATURE _______________|

Architecture Comparison: Stateless JWTs vs. Opaque Session Tokens

Engineering teams must weigh critical trade-offs between stateless JWT bearer tokens and stateful opaque session IDs (stored in Redis or relational databases):

Base64URL Encoding Why Standard atob Fails

JWT segments are not encoded using standard Base64 (RFC 4648 §4); they use Base64URL (RFC 4648 §5). Base64URL replaces '+' with '-', replaces '/' with '_', and strips all trailing '=' padding characters so the string can be safely passed in URL query strings and HTTP headers. To explore how binary padding functions, see our technical primer on What is Base64 Encoding.

If you pass a raw JWT segment to browser atob() or Node.js basic decoders without restoring padding and characters, it will throw an encoding exception or corrupt multi-byte UTF-8 unicode characters (such as accented letters or emojis in user names).

Zero Dependency JavaScript JWT Decoder

Here is a production-safe, client-side decoder function that handles Base64URL character replacements, re-applies standard 4-byte boundary padding, and safely decodes multi-byte UTF-8 payloads:

function decodeJwt(token) {
  if (typeof token !== "string") {
    throw new TypeError("Token must be a string");
  }

  const parts = token.trim().split(".");
  if (parts.length !== 3) {
    throw new Error("Invalid JWT format: must contain header, payload, and signature segments");
  }

  const decodeSegment = (segment) => {
    // 1. Replace Base64URL characters with standard Base64
    let base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
    
    // 2. Pad string with '=' until length is a multiple of 4
    while (base64.length % 4 !== 0) {
      base64 += "=";
    }

    // 3. Decode Base64 and handle UTF-8 multi-byte characters
    const binaryStr = atob(base64);
    const bytes = Uint8Array.from(binaryStr, (char) => char.charCodeAt(0));
    const jsonStr = new TextDecoder("utf-8").decode(bytes);
    
    return JSON.parse(jsonStr);
  };

  return {
    header: decodeSegment(parts[0]),
    payload: decodeSegment(parts[1]),
    signature: parts[2],
  };
}

// Example usage:
const sampleJwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzg5MCIsIm5hbWUiOiJBbGV4IFJpdmVyYSIsImV4cCI6MTc5ODc2MTYwMH0.abc";
console.log(decodeJwt(sampleJwt).payload);
// -> { sub: "user_890", name: "Alex Rivera", exp: 1798761600 }

Auditing Standard Claims exp nbf iat iss aud

The payload contains claims defined by RFC 7519 (detailed further in our JWT Structure and Claims Guide). When inspecting tokens during debugging or UI session routing, check these standard temporal claims:

• exp (Expiration Time): Unix epoch in seconds. If Date.now() >= exp * 1000, the token is expired and must be rejected.
• nbf (Not Before): Unix epoch in seconds. The token must not be accepted prior to this timestamp.
• iat (Issued At): Unix epoch in seconds indicating when the authentication authority minted the token.
• iss (Issuer): String identifying the identity provider (e.g. https://auth.company.com).
• aud (Audience): String or array of strings identifying the intended recipients or services.

Common Gotchas: Clock Skew Leeway & Sensitive Data Exposure

Two major operational gotchas occur when working with JWT claims in production:

1. Clock Skew Rejections: In distributed cloud clusters, the authentication server minting the token and the API gateway validating it may have clocks that differ by 1 to 5 seconds. If a token is issued with nbf set to exact current time, the API gateway may reject it as 'not yet valid'. Solution: Always configure a 30 to 60 second clock skew tolerance (leeway) in validation libraries.
2. Exposing Secrets in Payloads: Because JWT payloads are merely Base64URL-encoded (not encrypted), never store database passwords, API secret keys, or sensitive PII (Social Security numbers, medical records) in claims. Anyone inspecting browser LocalStorage or network proxies can read the entire payload.

Security Critical Decoding Is Not Verification

Decoding a JWT merely extracts JSON plaintext. Anyone with a text editor can modify {"role": "user"} to {"role": "admin"}, Base64URL-encode it, and send it to your backend.

[NEED: CoShareX JWT decoder privacy implementation detail — e.g. state that decoding runs 100% locally in browser memory with zero telemetry or network calls, making it safe for production bearer tokens and access credentials].