Understanding JSON Web Tokens and How to Decode Them

JSON Web Tokens (JWT) are a widely adopted standard for securely transmitting information between two parties. Commonly used in web development for authentication and authorization, a JWT allows a server to verify that a user is who they claim to be without needing to repeatedly query a database.

However, when you look at a raw JWT, it simply appears as a long, random string of letters, numbers, and symbols. This makes it impossible to read or troubleshoot at a glance. A JWT debugger tool helps developers and system administrators bridge this gap by translating that encoded string back into readable data, analyzing its validity, and verifying its digital signature.

This guide explains how JSON Web Tokens work, the components that make them up, and how to effectively use a debugger to analyze them.

The Anatomy of a JWT

A standard JSON Web Token consists of three distinct parts. These parts are encoded using a format called Base64Url and are separated by periods (.).

A typical token looks like this: xxxxx.yyyyy.zzzzz

When you paste a token into a debugger, the tool separates these three segments and decodes them to reveal the underlying information.

1. The Header (xxxxx)

The header typically consists of two parts: the type of the token (which is JWT) and the signing algorithm being used. The algorithm dictates how the token’s signature is generated.

Common algorithms include HMAC SHA256 (often written as HS256) or RSA. When decoded, a standard header looks like this basic JSON object:

JSON

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

2. The Payload (yyyyy)

The payload contains the actual data being transmitted, which are referred to as "claims." Claims are statements about an entity (usually the user) and additional metadata.

There are three main types of claims:

  • Registered claims: These are a set of predefined claims that are not mandatory but highly recommended to provide a set of useful, interoperable data. Examples include iss (issuer), exp (expiration time), sub (subject), and aud (audience).

  • Public claims: These can be defined at will by those using JWTs. However, to avoid collisions, they should be defined in the IANA JSON Web Token Registry or defined as a URI that contains a collision-resistant namespace.

  • Private claims: These are custom claims created to share information between parties that agree on using them. They are neither registered nor public.

A decoded payload might look like this:

JSON

{
  "sub": "1234567890",
  "name": "Jane Doe",
  "admin": true,
  "iat": 1516239022,
  "exp": 1516242622
}

3. The Signature (zzzzz)

The signature is the final part of the token. It 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.

To create the signature part, a system takes the encoded header, the encoded payload, a secret key, and the algorithm specified in the header, and signs them. If a token is altered in any way after it is signed—for instance, if a user tries to change "admin": false to "admin": true in the payload—the signature will no longer match, and the server will reject the token.

How the Debugger Tool Works

When working with APIs or building authentication systems, a JWT debugger is a standard utility. The tool processes the raw string in a few straightforward steps.

1. Base64Url Decoding The tool takes the first two segments of the token (Header and Payload) and reverses the Base64Url encoding. Base64Url is similar to standard Base64, but it replaces characters like + and / with - and _ so the token can be safely passed in URLs and HTTP headers without breaking the request format.

2. Expiration Analysis A robust debugger will specifically look for the exp (expiration) claim in the payload. The exp value is written as a Unix timestamp (the number of seconds since January 1, 1970). The tool converts this timestamp into a human-readable date and time, and compares it against the current system time to tell you immediately if the token is still valid or if it has expired.

3. Signature Verification Many debuggers allow you to input a secret key to test the signature. For tokens using the HS256 algorithm, the signature is generated using a symmetric secret string. If you provide that exact string to the tool, it will run the cryptographic math locally in your browser to see if the resulting signature matches the third part of your token.

Common Mistakes When Working with JWTs

Understanding the structure of a token is only half the process; implementing them securely requires knowing their limitations.

Treating Encoding as Encryption The most frequent misunderstanding about JWTs is assuming the payload is secure from prying eyes. Base64Url is an encoding format, not an encryption method. Anyone who intercepts a JWT can decode the payload and read its contents. Therefore, you should never place sensitive information—like passwords, social security numbers, or internal system secrets—inside a standard JWT payload.

Ignoring Token Expiration Tokens should have a limited lifespan. If a token lacks an exp claim, it is technically valid forever unless the server maintains a blocklist (which defeats the stateless purpose of using a JWT). Best practices suggest keeping token lifespans short (e.g., 15 to 30 minutes) and using a separate "refresh token" mechanism to get a new JWT when the old one expires.

Relying on the Payload Before Verifying the Signature A system should never read the payload and trust its contents without first validating the signature. Because decoding a token is easy, a malicious user could decode a token, alter the data, re-encode it, and send it to the server. If the server does not verify the cryptographic signature against its own secret key, it will accept the tampered data as truth.

Frequently Asked Questions

Can I edit a token to change its data? You can decode the token, edit the JSON payload, and re-encode it back into Base64Url format. However, you cannot generate a valid signature for your edited token unless you know the server's private secret key. When you send the altered token to the server, the signature verification will fail, and your request will be denied.

Why does my token only have two dots and empty space at the end? A JWT requires three parts, meaning it must have two dots. If the signature portion is missing entirely (leaving just header.payload.), it usually indicates that the token was generated with the "none" algorithm. This is a severe security vulnerability that modern systems reject, as it means the token is unsigned and untrusted.

What is the difference between HS256 and RS256? HS256 (HMAC with SHA-256) is a symmetric algorithm. It uses the exact same secret key to both create the signature and verify it. This is fast and common but requires sharing the secret if multiple services need to verify the token.

RS256 (RSA Signature with SHA-256) is an asymmetric algorithm. It uses a private key to create the signature and a public key to verify it. This is preferred in complex systems because you can distribute the public key widely without allowing anyone else to create new tokens.

Is it safe to paste my JWT into an online debugger? While many client-side tools process data entirely in your browser without sending it to an external server, it is a standard security best practice to never paste a live, production token—especially one belonging to an active user or admin—into a third-party tool. For debugging, it is always safer to generate test tokens in a local development environment.

Disclaimer: This information is provided for educational and debugging purposes only. Understanding token structures does not replace the need for comprehensive security audits in software development. Always handle cryptographic keys securely and ensure that production tokens are not exposed to unauthorized third-party services or stored in plain text.