How to decode a JWT: the safe way in 2026

When working with authentication systems, I often encounter JSON Web Tokens (JWTs) that need to be decoded and verified. A JWT is a compact, URL-safe means of representing claims to be transferred between two parties. The token consists of three parts: a header, a payload, and a signature, all of which are Base64URL-encoded. To decode a JWT, it's essential to understand the structure and the encoding scheme used.

#TL;DR

• A JWT consists of a header, payload, and signature, all Base64URL-encoded.
• The header contains the algorithm used for signing, while the payload contains the claims.
• To verify a JWT, the signature must be verified using the corresponding secret key or public key.
• Never paste tokens into random websites, as this can lead to security vulnerabilities.
• Use a trusted JWT decoder to decode and verify tokens.

#Understanding JWT Structure

A JWT is structured as follows: header.payload.signature. The header typically contains the algorithm used for signing, such as HS256 or RS256. The payload contains the claims, which can include user information, expiration time, and other relevant data. The signature is generated by signing the header and payload with a secret key or private key.

#Base64URL Alphabet

The Base64URL alphabet is a modified version of the standard Base64 alphabet, where the + and / characters are replaced with - and _, respectively. This is done to make the encoded string URL-safe. To encode a string using Base64URL, you can use a library or a tool like the base64-encode-decode tool.

#Decoding a JWT

To decode a JWT, you need to separate the three parts and decode each part individually. The header and payload can be decoded using a Base64URL decoder, while the signature needs to be verified using the corresponding secret key or public key. You can use a library like jsonwebtoken in Node.js to decode and verify JWTs.

const jwt = require('jsonwebtoken');

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaGFuIjoiMjMwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
const decoded = jwt.decode(token, { complete: true });
console.log(decoded.header);
console.log(decoded.payload);

#Verifying a JWT Signature

Verifying a JWT signature is crucial to ensure the authenticity of the token. The signature is generated by signing the header and payload with a secret key or private key. To verify the signature, you need to use the corresponding secret key or public key. If the signature is invalid, the token is considered tampered with and should not be trusted.

const jwt = require('jsonwebtoken');

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaGFuIjoiMjMwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
const secretKey = 'your-secret-key';

try {
  jwt.verify(token, secretKey);
  console.log('Signature is valid');
} catch (err) {
  console.log('Signature is invalid');
}

#Using a JWT Decoder

When working with JWTs, it's often convenient to use a JWT decoder to decode and verify tokens. You can paste the token into our JWT decoder to decode and verify it. This can save you time and effort, especially when working with complex tokens.

#Common mistakes

• Pasting tokens into random websites, which can lead to security vulnerabilities.
• Not verifying the signature of a JWT, which can lead to accepting tampered tokens.
• Using a weak secret key or private key, which can lead to signature forgery.
• Not handling token expiration, which can lead to security issues.
• Not validating token claims, which can lead to security issues.

#FAQ

#Is Base64 encryption?

Base64 is an encoding scheme, not an encryption scheme. It is used to represent binary data as a string of characters.

#What is the difference between HS256 and RS256?

HS256 and RS256 are two different algorithms used for signing JWTs. HS256 uses a secret key, while RS256 uses a private key.

#Can I use a JWT decoder to verify a token?

Yes, a JWT decoder can be used to verify a token, but it's essential to use a trusted decoder to avoid security vulnerabilities.

#How do I handle token expiration?

Token expiration should be handled by verifying the expiration time claim in the payload and rejecting the token if it has expired.

#What is the attack surface of a JWT?

The attack surface of a JWT includes signature forgery, token tampering, and information disclosure. It's essential to use a secure secret key or private key and to handle tokens securely.

#Wrapping up

In conclusion, decoding a JWT requires understanding the structure and encoding scheme used. It's essential to use a trusted JWT decoder and to verify the signature of the token to ensure its authenticity. By following best practices and using trusted tools, you can handle JWTs securely and avoid common mistakes. For more information on JWTs, you can refer to the RFC 7519 and RFC 7515 specifications.