How to Decode JWT Tokens Online: A Complete Step-by-Step Guide

What is a JWT Token?

JSON Web Token (JWT) is a compact, self-contained method for securely transmitting information between parties as a JSON object. It's widely used in modern web applications for authentication and authorization. A JWT consists of three parts separated by dots (.), each encoded in Base64URL format.

JWT Structure: Header.Payload.Signature

Every JWT token follows a consistent structure with three distinct sections:

Base64URL Encoding

JWT uses Base64URL encoding rather than standard Base64. This encoding is URL-safe, replacing + with -, / with _, and removing padding (=). This makes JWTs suitable for use in URLs and HTTP headers without special encoding.

Why Would You Need to Decode a JWT?

Understanding when and why to decode JWTs is essential for any developer working with modern authentication systems. Here are the most common scenarios:

• Debugging Authentication Issues: When users report login problems, decoding the token helps identify missing or invalid claims that prevent authorization.
• Checking Token Expiry: Verify the exp claim to determine if a token has expired and needs refresh.
• Inspecting User Claims: View embedded user information such as roles, permissions, and custom data without making additional database queries.
• Troubleshooting Permissions Errors: Confirm that the expected claims are present and correctly formatted.
• Testing Auth Flows: Verify that your authentication service generates tokens with the correct structure and data.
• Security Audits: Ensure sensitive data is not being stored in the token payload (which can be decoded publicly).

How to Decode a JWT Online

The easiest way to decode JWT tokens without any installation is to use our free online JWT decoder. Here's a step-by-step guide:

Using the Kas JWT Decoder

1. Visit kas.storksoft.by/jwt-decoder
2. Copy your JWT token (the complete token with all three parts separated by dots)
3. Paste it into the "JWT Token" input field
4. The decoder instantly displays:
   • Decoded header with algorithm and token type
   • Decoded payload with all claims and custom data
   • Signature validation status (if you provide the secret)
5. Optionally, enter your secret key to verify the token's signature

Expected Output for Sample Token

When you decode the sample token above, you should see:

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

Decoded Payload:
{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Understanding JWT Claims

The payload of a JWT contains "claims" — assertions about the user or token. Claims are key-value pairs that carry meaningful information. JWT defines several standard claims, and applications can add custom claims.

Real-World Example

Here's a more realistic JWT payload with standard and custom claims:

{
  "sub": "user_12345",
  "email": "john@example.com",
  "name": "John Doe",
  "roles": ["admin", "user"],
  "iss": "https://auth.example.com",
  "aud": "api.example.com",
  "iat": 1673456789,
  "exp": 1673543189,
  "nbf": 1673456789,
  "jti": "token_unique_id_xyz"
}

When analyzing a JWT, the exp claim is critical. If the current time exceeds this value, the token is expired and should be refreshed. The roles claim demonstrates custom data used for authorization decisions.

JWT Security Best Practices

While JWT is a powerful authentication mechanism, it requires careful implementation. Follow these best practices to secure your tokens:

1. Never Store Secrets in the Payload

The payload is Base64URL-encoded, not encrypted. Anyone with the token can decode and read it. Never include passwords, API keys, credit card numbers, or other sensitive data.

2. Always Verify the Signature

Before trusting any claims in a token, verify its signature using the issuer's public key or secret. A valid signature proves the token hasn't been tampered with and was issued by a trusted authority.

3. Check Token Expiration

Always validate the exp claim. If a token has expired, reject it and request a new one. This limits the damage if a token is compromised.

4. Use HTTPS Only

Always transmit JWTs over encrypted HTTPS connections. Sending tokens over HTTP exposes them to interception.

5. Store Tokens Securely

In web applications, store JWTs in HTTP-only, secure cookies when possible. If storing in localStorage, be aware of XSS vulnerabilities.

6. Implement Token Rotation

Use short expiration times and refresh tokens. When a token expires, users must obtain a new one using their refresh token, limiting the window of exposure for compromised tokens.

7. Use Strong Signing Algorithms

Use robust algorithms like HS256 or RS256. Avoid deprecated algorithms, and ensure your secret keys are sufficiently random and long.

Recommended Algorithms:
HS256: HMAC with SHA-256 (symmetric)
RS256: RSA with SHA-256 (asymmetric)
ES256: ECDSA with SHA-256 (asymmetric)

Common JWT Errors and Fixes

When working with JWTs, you'll encounter several common errors. Here's how to diagnose and fix them:

Error: Token Expired

Cause: The token's expiration time has passed.

Fix: Request a new token or use the refresh token to obtain a fresh access token.

Error: Invalid Signature

Cause: The signature doesn't match the header and payload, or the wrong key was used to verify it.

Fix: Ensure you're using the correct secret key or public certificate. Verify the token hasn't been modified.

Error: Malformed Token

Cause: The token doesn't have the correct structure (three parts separated by dots).

Fix: Check that you've copied the entire token, including all three parts. Use a JWT decoder to validate the structure.

Error: Invalid Claims

Cause: Required claims are missing or have unexpected values.

Fix: Decode the token to verify all required claims are present. Check the aud and iss claims match your application's expectations.

Debugging Tool: Use Our JWT Decoder

When you encounter any JWT error, paste the token into our JWT decoder to inspect the header, payload, and verify the structure is correct.

Decoding JWTs Programmatically

While online tools are convenient for debugging, your application needs to decode and verify JWTs programmatically. Here are examples in popular languages:

JavaScript (Node.js)

Using the popular jsonwebtoken library:

JavaScript Example:
const jwt = require('jsonwebtoken');

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const secret = 'your-secret-key';

try {
  // Verify and decode the token
  const decoded = jwt.verify(token, secret);
  console.log('Token is valid');
  console.log('User ID:', decoded.sub);
  console.log('Name:', decoded.name);
} catch (error) {
  if (error.name === 'TokenExpiredError') {
    console.log('Token has expired');
  } else if (error.name === 'JsonWebTokenError') {
    console.log('Invalid token:', error.message);
  }
}

Python

Using the PyJWT library:

Python Example:
import jwt
from datetime import datetime

token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
secret = 'your-secret-key'

try:
  # Decode and verify the token
  decoded = jwt.decode(token, secret, algorithms=['HS256'])
  print('Token is valid')
  print('User ID:', decoded['sub'])
  print('Expires at:', datetime.fromtimestamp(decoded['exp']))
except jwt.ExpiredSignatureError:
  print('Token has expired')
except jwt.InvalidTokenError as e:
  print('Invalid token:', str(e))

Python - Decode Without Verification (Debugging Only)

For quick debugging, you can decode without verification, but never do this in production:

Python - Debug Only:
import jwt
import json
import base64

# For debugging only - do NOT use in production
token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

try:
  decoded = jwt.decode(token, options={"verify_signature": False})
  print(json.dumps(decoded, indent=2))
except jwt.DecodeError as e:
  print('Token structure is invalid:', str(e))

Installation

To use JWT libraries in your project:

Install JWT Library:
# JavaScript/Node.js
npm install jsonwebtoken

# Python
pip install PyJWT

Free Tools for Working with JWTs

Beyond JWT decoding, developers need a range of tools for authentication and security tasks. Here are essential free tools available at Kas Developer Tools:

Why These Tools Matter

Working with JWTs often requires understanding related concepts like Base64 encoding, hashing, and HTTP authentication headers. Our integrated suite of tools provides everything you need in one place, with a consistent dark theme and fast, client-side processing for privacy and speed.