JWT Decoding: Understanding JSON Web Tokens Safely

JSON Web Tokens (JWT) are an open standard (RFC 7519) for representing claims securely between two parties. They have become the de-facto standard for stateless authentication in modern web applications, microservices, and Single Page Applications (SPAs).

In this guide, we'll deep-dive into the internal structure of these tokens and show you how to use our JWT Decoder tool to debug your authentication flows safely.

The Three Components of a JWT

A JWT is a single string of Base64Url encoded characters, but internally, it is always composed of three distinct parts separated by a dot (.):

Header: The Metadata

The header typically consists of two parts: the type of the token (JWT) and the signing algorithm being used, such as HS256 (HMAC with SHA-256) or RS256 (RSA with SHA-256).

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

Payload: The Claims

The payload contains the "claims." Claims are statements about an entity (typically, the user) and additional data. There are three types of claims: registered, public, and private claims.

• Registered claims: iss (issuer), exp (expiration time), sub (subject), aud (audience).
• Public/Private claims: Any custom data you want to share, like userId or userRole.

Signature: The Security

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

Why You Must Decode JWTs Safely

When debugging an authentication issue, you often need to see the exp (expiration) or sub (subject) of a token.

[!CAUTION] Never paste production JWTs into an unknown online decoder. If the decoder sends your token to a backend server, your production session can be hijacked. Always use a client-side only decoder like our JWT Decoder which processes the token entirely in your browser.

How to Debug with Our JWT Decoder

Our tool provides a secure, visual interface for understanding your tokens:

1. Input: Paste your token. The tool instantly splits it into Header, Payload, and Signature segments.
2. Analysis: We automatically convert UNIX timestamps (like exp and iat) into human-readable dates, helping you spot expired tokens instantly.
3. Integrity Check: While the tool is primarily for decoding, it ensures the Base64Url structure is valid before displaying the claims.

JWT Security Checklist

If you are implementing JWTs in your project, follow this professional safety checklist:

• Don't Put Secrets in the Payload: Treat the payload as a public document. Never store passwords, API keys, or PII.
• Enforce Algorithm Verification: On your server, explicitly define which algorithms (e.g., ["HS256"]) are allowed to prevent "alg: none" attacks.
• Set Short Expirations: Tokens should be short-lived. Use Refresh Tokens for long-running sessions.
• Use Strong Secrets: For HMAC algorithms, use a secret that is at least as long as the hash output (e.g., 256 bits).
• Check the exp Claim: Your server-side library must always reject tokens that have passed their expiration date.

Common JWT Issues & Fixes

• Invalid Signature: Usually caused by a secret mismatch between the issuer and the validator.
• Token Expired: Check if your server time is out of sync with your auth provider (e.g., Auth0, Firebase).
• Malformed Token: Ensure you aren't accidentally including the Bearer prefix when pasting into decoders.

Need to encode or decode raw data instead? Try our Base64 Tool or use the Hash Generator to create secure secrets for your JWT signing keys.