How to Decode JWT Tokens Safely (Without Exposing Secrets)

What is a JWT?

A JSON Web Token (JWT) is a compact, URL-safe token format used for authentication and information exchange. JWTs are everywhere in modern web development — they carry user identity between services, authorize API requests, and encode session data. Understanding how to read and debug them is an essential developer skill.

A JWT consists of three parts separated by dots:

• Header — specifies the token type (JWT) and the signing algorithm (e.g., HS256, RS256).
• Payload — contains claims, which are statements about the user and metadata like expiration time.
• Signature — verifies that the token has not been tampered with.

Each part is Base64URL-encoded. The header and payload are readable by anyone who has the token — they are encoded, not encrypted.

Why safe decoding matters

JWT tokens often contain sensitive information: user IDs, email addresses, roles, permissions, and session metadata. When you paste a JWT into an online decoder that sends it to a server, you are potentially exposing all of that data to a third party. Even if the service promises to delete the token, you have no way to verify that.

The JWT Decoder at Xevon Tools runs entirely in your browser. Your token is decoded using JavaScript's built-in atob function and never leaves your device. This is critical when debugging production tokens that contain real user data.

Step-by-step: decoding a JWT

1. Open the JWT Decoder.
2. Paste your JWT into the input field.
3. The tool instantly displays the decoded header and payload as formatted JSON.
4. Review the claims — check the expiration time (exp), issued-at time (iat), subject (sub), and any custom claims.

If the token is malformed, the tool will show an error indicating which part failed to decode.

Understanding common JWT claims

Here are the standard claims you will encounter most often:

• iss (issuer) — Who created the token (e.g., your auth server's URL).
• sub (subject) — Who the token represents (usually a user ID).
• aud (audience) — Who the token is intended for (e.g., your API's identifier).
• exp (expiration) — When the token expires, as a Unix timestamp.
• iat (issued at) — When the token was created.
• nbf (not before) — The earliest time the token is valid.
• jti (JWT ID) — A unique identifier for the token.

Custom claims can contain anything — roles, permissions, organization IDs, feature flags — depending on your application.

Debugging with related tools

JWT debugging often involves multiple tools:

Base64 Decoder

Each part of a JWT is Base64URL-encoded. The Base64 Encoder/Decoder lets you manually decode individual sections if you want to inspect them outside of the JWT Decoder. Base64URL differs slightly from standard Base64 — it uses hyphens instead of plus signs and underscores instead of slashes — but most decoders handle both variants.

JSON Formatter

The decoded header and payload are JSON objects. If you need to compare, search, or manipulate the decoded content, paste it into the JSON Formatter for proper indentation and syntax highlighting.

Common JWT debugging scenarios

Token expired

If API requests are failing with 401 errors, check the exp claim. Convert the Unix timestamp to a human-readable date (the JWT Decoder does this automatically) and compare it to the current time. If the token is expired, the client needs to refresh it.

Wrong audience or issuer

If a token is rejected by a service, check the aud and iss claims. They must match what the receiving service expects. Mismatches often happen in environments with multiple auth servers or when tokens are accidentally sent to the wrong API.

Missing claims

If authorization logic is failing, check whether the expected claims (roles, permissions, scopes) are actually present in the token. A common bug is issuing tokens without the necessary custom claims.

Security reminders

• Never trust the payload without verifying the signature. The payload can be modified by anyone. Verification requires the signing key, which only the server should have.
• Never store sensitive data in JWTs. Since anyone with the token can decode the payload, do not put passwords, credit card numbers, or other secrets in claims.
• Always decode tokens locally. Use browser-based tools rather than sending tokens to third-party servers.
• Set reasonable expiration times. Short-lived tokens reduce the window of exposure if a token is compromised.

JWTs are a powerful authentication mechanism, but debugging them requires understanding their structure and having the right tools. A browser-based decoder that respects your privacy is the safest way to inspect tokens during development and troubleshooting.