How to Decode JWT Tokens Safely (Without Leaking Secrets)

What Is a JWT?

A JSON Web Token (JWT) is a compact, URL-safe way to represent claims between two parties. It's the most common format for authentication tokens in modern web apps.

A JWT looks like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Three parts separated by dots: header, payload, and signature.

The Three Parts Explained

Header

Base64URL-encoded JSON specifying the algorithm and token type:

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

Payload

Base64URL-encoded JSON containing the claims:

{"sub": "1234567890", "name": "John Doe", "iat": 1516239022}

Common claims: sub (subject/user ID), exp (expiration), iat (issued at), iss (issuer), aud (audience).

Signature

The header and payload are signed with a secret key. This prevents tampering — if anyone modifies the payload, the signature won't match.

Why You Need to Decode JWTs During Debugging

Common debugging scenarios:

• 401 errors — Is the token expired? Check the exp claim.
• Wrong permissions — Does the token contain the right roles/scopes?
• Wrong user — Is the sub claim the user you expect?
• Algorithm confusion — Is the token using the algorithm your server expects?

The Security Risk of Online Decoders

Here's the problem: most online JWT decoders send your token to their server for processing. A JWT might contain:

• User IDs and email addresses
• Role and permission information
• Internal service identifiers
• Session identifiers

Pasting a production JWT into a random website means sending this data to an unknown third party.

Decode JWTs Safely

Use a tool that runs entirely in your browser. Our [free JWT decoder](/tools/jwt-decoder) processes everything client-side — no data leaves your machine. It shows:

• Decoded header (algorithm, type)
• Decoded payload (all claims, formatted)
• Expiration status (valid or expired, with exact date)

Common JWT Mistakes

1. Storing Sensitive Data in the Payload

JWT payloads are encoded, not encrypted. Anyone with the token can read the payload. Never put passwords, credit card numbers, or secrets in a JWT.

2. Not Checking Expiration

Always validate exp on the server. A token that expired 5 seconds ago is not valid, even if the signature is correct.

3. Using `none` Algorithm

Some JWT libraries accept tokens with alg: "none" — meaning no signature verification. Always validate the algorithm on the server side.

Debugging Auth Errors in Production

If you're manually decoding JWTs to debug 401/403 errors, you're doing the error tracking tool's job. Bugsly automatically captures authentication errors with token metadata (expiration, issuer, algorithm — never the full token) so you can diagnose auth issues without manual JWT inspection. [Try it free](/signup).