The Ultimate Guide to JWTs: Decode, Inspect & Debug

In the modern web, the JSON Web Token (JWT) has become the de facto standard for securing APIs and managing user sessions. Whether you are using Auth0, Firebase, AWS Cognito, or a custom Node.js backend, you are likely passing these long, cryptic strings in your Authorization headers.

But since JWTs are just Base64Url-encoded strings, they are opaque to the human eye. You can't just "read" them to see if a user has the admin role or if the token has expired. That is where our JWT Decoder & Inspector comes in. typically used to debug authentication issues instantly.

Anatomy of a JWT

A JWT is not encrypted; it is encoded and signed. It consists of three parts separated by dots (.):

aaaaaa.bbbbbb.cccccc
(Header).(Payload).(Signature)
    

1. Header (Red)

Describes how the token is signed. It usually looks like this:

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

2. Payload (Purple)

Contains the "Claims" (data). This is what you care about. Standard claims include:

• iss (Issuer): Who created this token? (e.g., `https://accounts.google.com`).
• sub (Subject): Who is this token for? (e.g., user ID `12345`).
• aud (audience): Who should accept this token? (e.g., `my-api-server`).
• exp (Expiration): Unix timestamp of when the token dies.
• iat (Issued At): Unix timestamp of when it was created.
• Custom Claims: Your own data, like `{"role": "admin"}`.

3. Signature (Blue)

This is the integrity check. The server takes the Header and Payload, combines them with a Secret Key, and hashes them using the algorithm specified in the header. If even one character of the payload changes, the signature changes completely.

Security: Signing vs. Encryption

Crucial Concept: JWTs are (usually) NOT encrypted. Anyone who intercepts the token can read the payload.

Algorithms: HS256 vs RS256

There are two main ways to sign a token:

HS256 (HMAC with SHA-256)

Symmetric. The server uses a single secret key (e.g., `my_secret_password`) to both SIGN and VERIFY tokens.

• Pros: Faster, simpler code.
• Cons: You cannot share the key with clients. If the key leaks, anyone can forge tokens.

RS256 (RSA Signature with SHA-256)

Asymmetric. The server has a Private Key to SIGN tokens. The client (or other APIs) has a Public Key to VERIFY them.

• Pros: Safe to share the Public Key. Great for microservices.
• Cons: Slower to generate/verify.

Debugging Common JWT Issues

1. "Token Expired" (401 Unauthorized)

Paste your token into our tool and look at the exp claim. Compare it to the "Current Time" displayed. If exp < current_time, the token is dead. You need to refresh it.

2. "Invalid Signature"

This means either:

• The token was tampered with (someone tried to change `role: user` to `role: admin`).
• The server rotated its secret keys.
• You are validating an HS256 token using an RS256 library (or vice versa).

The "None" Algorithm Attack

In the past, some libraries allowed tokens with `alg: "none"`. Attackers would modify the payload, set the algorithm to "none", remove the signature, and the server would accept it. Modern libraries (and our tool) warn you about insecure algorithms.

Need to verify the timestamp manually? Use our Epoch Converter.