How to Decode JWT Safely

What is a JWT?

A JWT (JSON Web Token) is a compact, URL-safe token that represents claims between two parties. It is commonly used for authentication: after a user logs in, the server issues a JWT that the client includes in subsequent requests to prove their identity. The server verifies the token to authenticate the request without needing to look up a session in a database.

JWTs are self-contained, meaning the token itself carries the information needed to identify the user. This makes them stateless and scalable, but it also means that anyone who has the token can read its contents. This is why JWTs should always be transmitted over HTTPS.

JWT structure explained

A JWT consists of three parts separated by dots: header.payload.signature. The header specifies the token type and the signing algorithm. The payload contains the claims, which are statements about the user or the token itself, such as the user ID, expiration time, and issuer. The signature is used to verify that the token has not been tampered with.

Both the header and payload are base64url-encoded JSON objects. They are not encrypted, which means anyone can decode and read them. The signature is created using the header, payload, and a secret key known only to the server. The signature ensures the token integrity but does not hide its contents.

Decoding vs verifying

Decoding a JWT means reading the header and payload by base64-decoding them. This does not require any secret key and can be done by anyone who has the token. Decoding lets you inspect the claims, check the expiration, and debug authentication issues.

Verifying a JWT means checking the signature to confirm that the token has not been tampered with and was issued by a trusted source. Verification requires the secret key (for HMAC algorithms) or the public key (for RSA and ECDSA algorithms). Only the server should perform verification, as it holds the secret key.

Decoding is safe to do in the browser because it only reads the token contents. Verification should be done server-side because it requires the secret key, which should never be exposed to the client.

Step-by-step: decoding a JWT

1. Open a browser-based JWT decoder like ToolKit at toolkit.explorme.com.

2. Paste the JWT token into the input field. The token is a long string with two dots separating the three parts.

3. The tool instantly decodes the header and payload and displays them as formatted JSON.

4. Review the header to see the token type and signing algorithm.

5. Review the payload to see the claims, such as the issuer (iss), subject (sub), expiration (exp), and issued at (iat).

6. Check the expiration claim to see if the token is still valid. The exp claim is a Unix timestamp.

7. The tool processes the token entirely in your browser. No data is sent to a server.

Security considerations

JWTs are not encrypted. Anyone who has the token can read its contents. This means you should never put sensitive information like passwords or credit card numbers in a JWT payload. The token is designed for authentication claims, not for storing sensitive data.

Always transmit JWTs over HTTPS to prevent interception. If a token is stolen, the attacker can use it to impersonate the user until it expires. Use short expiration times and implement token refresh strategies to limit the window of opportunity for stolen tokens.

Never paste production JWTs into untrusted online tools. Use a client-side decoder that processes the token in your browser and does not transmit it. ToolKit at toolkit.explorme.com decodes JWTs entirely client-side.

Common use cases

Decoding JWTs is useful for debugging authentication flows. You can check the expiration time to see if a token has expired, inspect the user ID to confirm the correct user is authenticated, verify the issuer to ensure the token came from the expected source, and review custom claims to debug authorization issues.

When developing authentication features, decoding the JWT helps you understand what the server is sending and whether the client is handling it correctly. It is also useful for verifying that token refresh logic is working as expected.