How to Safely Inspect a JWT During Debugging

Every backend developer has been here: you're debugging an auth issue, you have a JWT in your hands, and you need to see what's inside it to figure out what's wrong. Maybe the claims are wrong, maybe the token is expired, maybe the algorithm is unexpected. You need to decode it.

The problem is that most online JWT decoders are black boxes. You paste in a token — a token that contains the user's identity, their permissions, and their session — and you have no idea whether that token was logged, indexed, or sent to someone else's server.

Why this matters

A JWT is not just a random string. It carries authentication. If your token leaks to a third party before it expires, that third party can impersonate the user until the expiration time passes. For short-lived tokens (15 minutes) this is bad. For long-lived tokens (weeks or months) it can be catastrophic.

The usual advice is "only decode JWTs on trusted tools" — but what does trusted mean? A tool you downloaded from a stranger on GitHub? A browser extension that has access to every website you visit? A hosted decoder you've never audited?

The safest option: decode locally

The safest way to decode a JWT is to use a tool that runs entirely in your browser with no network activity after the page loads. This way you can see exactly what the tool does: it loads once, then processes your token locally, and never transmits anything.

You can verify this yourself:

• Open the tool page.
• Open your browser's DevTools Network tab.
• Disconnect your internet (airplane mode or toggle Wi-Fi off).
• Paste your JWT.
• Confirm the decoded header and payload appear — proving no network request was needed.

Catalyst's JWT Decoder works this way. Every JWT decoding operation happens in pure client-side JavaScript using atob() for the Base64-URL portions and JSON.parse() for the header and payload. The token is never sent anywhere.

What decoding gives you

A decoded JWT has three parts:

Header

Contains the algorithm (alg) and token type (typ). Look here if you're debugging algorithm mismatches — e.g. the server expects RS256 but the token is signed with HS256.

Payload (claims)

The meat of the token. Standard claims include sub (subject / user ID), iat (issued at), exp (expiration), iss (issuer), aud (audience), and any custom claims your application adds. When debugging an auth failure, check exp first — expired tokens are by far the most common cause.

Signature

The cryptographic proof that the header and payload haven't been modified. A decoder alone cannot verify the signature — that requires the signing key. Decoding and verifying are separate steps.

When to verify vs. when to decode

If you just want to understand what's in a token — during debugging, incident response, or code review — decoding is enough. If you need to trust the contents (e.g. in production middleware that extracts claims), you must also verify the signature using the same secret or public key the server uses to sign tokens.

Catalyst has separate tools for each: the JWT Decoder for read-only inspection, and the JWT Builder for constructing and signing new tokens during development.