How to Safely Decode, Validate, and Debug JWT Payloads: Base64URL, JSON Claims, and Header Inspection

What Is a JSON Web Token (JWT) and How Is It Structured?

In modern web development, microservice architectures, and single-page applications (SPAs), JSON Web Tokens (JWTs) are the de facto open standard (RFC 7519) for securely transmitting digitally signed claims between a client and a server.

From authentication workflows using OAuth 2.0 and OpenID Connect (OIDC) to federated identity providers like Auth0, Supabase, Firebase, and AWS Cognito, JWTs act as stateless session credentials.

A standard JWT consists of three distinct parts separated by periods (.):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkphbmUgRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header (Red): Declares token type (typ: "JWT") and signing algorithm (alg: "HS256" or "RS256").
2. Payload (Purple): Contains the claims, user metadata, roles, permissions, and expiration timestamps.
3. Signature (Blue): A cryptographic hash generated with a secret key or private certificate to verify integrity.

---

Standard Base64 vs. Base64URL: Why Padding and Characters Matter

Many developers assume that JWT parts are encoded in standard Base64. However, JWTs use Base64URL encoding, a URL-safe variation designed to be transmitted safely in HTTP request headers, query strings, and cookies.

Parameter	Standard Base64 (RFC 4648 §4)	Base64URL (RFC 4648 §5)	Purpose in JWTs
Character 62	+ (Plus sign)	- (Minus sign / hyphen)	Avoids URI query string encoding issues
Character 63	/ (Forward slash)	_ (Underscore)	Prevents path delimiter misinterpretation
Padding	= (Equal signs)	Omitted / Stripped	Keeps token strings lean in HTTP headers

When debugging tokens manually, passing a Base64URL string into a standard Base64 decoder without converting - to +, _ to /, and restoring = padding will cause decode exceptions.

---

Step-by-Step: Manually Decoding JWT Components

You can inspect and debug each segment of a JWT using client-side developer utilities:

1. Split the Token: Separate the JWT into its three parts by splitting on the period (.).
2. Decode Base64URL: Use Base64 Converter to decode the header and payload strings into raw JSON text.
3. Format & Validate JSON: Paste the resulting JSON text into JSON Formatter to inspect structured claims, indentation, and syntax trees.

---

Understanding Registered JWT Claims

RFC 7519 defines several standard registered claim keys that every developer should understand when debugging authentication flows:

• iss (Issuer): Identifies the identity provider or authorization server that issued the token (e.g. https://auth.company.com/).
• sub (Subject): The unique identifier (UUID or ID) of the authenticated user.
• aud (Audience): The target resource server or API endpoint for which the token is intended.
• exp (Expiration Time): Unix timestamp (seconds since Epoch) after which the token is invalid.
• nbf (Not Before): Unix timestamp before which the token must not be accepted.
• iat (Issued At): Unix timestamp indicating when the token was generated.

---

Calculating Expiration Timestamps

Because exp timestamps are expressed in Unix seconds (e.g. 1738752000), calculating whether a token is active or expired requires comparing it against the current Unix time:

const payload = JSON.parse(atob(jwt.split('.')[1]));
const isExpired = Date.now() >= payload.exp * 1000;
const expiresAt = new Date(payload.exp * 1000).toLocaleString();

console.log(`Token expires on: ${expiresAt}`);
console.log(`Is Token Expired? ${isExpired}`);

---

Comparing Token Payloads Across Environments with Diff Checker

During staging and production deployments, permission bugs frequently arise when a user role or scope claim is missing between environments.

By taking the formatted JSON payload from your staging environment and comparing it against your production token in Diff Checker:

• Instantly highlight missing scopes (e.g. "scope": "read:billing admin").
• Detect subtle tenant ID mismatches or algorithm downgrades ("alg": "none").
• Validate claim consistency across OAuth microservice flows.

---

The Danger of Online JWT Debuggers for Production Credentials

When an authentication bug occurs in production, developers often search for online token decoders and paste real user tokens containing live session keys, user emails, and authorization scopes into random websites.

If that third-party website logs inputs or transmits tokens to remote analytics servers, your production access tokens are compromised.

With JSON Formatter and Base64 Converter on Utilify:

• All decoding, syntax highlighting, and JSON tree formatting execute 100% locally in your browser's JavaScript engine.
• No data is transmitted to external servers, protecting your sensitive API credentials and customer sessions.