ByteTools Logo

JWT Decoding Guide: How to Decode and Verify JSON Web Tokens

Master JWT decoding and verification for secure authentication. Learn token structure, claims validation, signature verification, and security best practices.

Try Our JWT Decoder

Table of Contents

What is JWT?

JWT (JSON Web Token) is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. JWTs are commonly used for authentication and information exchange in web applications.

Why Use JWT?

Benefits

  • • Stateless - No server-side session storage
  • • Portable - Can be used across different domains
  • • Compact - Small size for HTTP headers
  • • Self-contained - Contains all necessary information

Considerations

  • • Size - Larger than session IDs
  • • Cannot revoke - Valid until expiration
  • • Sensitive data - Payload is readable
  • • Key management - Requires secure secret handling

JWT Structure

A JWT consists of three Base64-encoded parts separated by dots:

header.payload.signature
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header

Contains metadata about the token:

{
"alg": "HS256",
"typ": "JWT"
}
  • • alg: Signing algorithm
  • • typ: Token type

Payload

Contains claims (statements about the user):

{
"sub": "1234567890",
"name": "John Doe",
"iat": 1516239022,
"exp": 1516242622
}
  • • sub: Subject (user ID)
  • • iat: Issued at time
  • • exp: Expiration time

Signature

Verifies token integrity:

HMACSHA256(
base64UrlEncode(header) +
"." +
base64UrlEncode(payload),
secret
)
  • • Prevents tampering
  • • Requires secret key
  • • Verifies authenticity

JWT Decoding Process

Decoding a JWT involves extracting and parsing each part:

Step-by-Step Decoding

1

Split the Token

Separate the token at the dots (.) to get three parts

const [header, payload, signature] = token.split('.');
2

Base64 Decode

Decode each part from Base64URL encoding

const decodedHeader = JSON.parse(atob(header));
const decodedPayload = JSON.parse(atob(payload));
3

Parse JSON

Convert the decoded strings to JSON objects

// Now you have readable header and payload objects

Important Note

Decoding only reveals content - it doesn't verify authenticity. Always validate the signature on the server!

Understanding JWT Claims

Claims are statements about an entity (typically the user) and additional data:

Standard Claims

"iss" (Issuer)
Who issued the token
Example: "https://auth.example.com"
"sub" (Subject)
Who the token is about
Example: "user123" or "john@example.com"
"aud" (Audience)
Who should accept the token
Example: "api.example.com"
"exp" (Expiration)
When the token expires
Unix timestamp: 1704067200
"iat" (Issued At)
When the token was issued
Unix timestamp: 1704063600

Custom Claims

"name"
User's full name
Example: "John Doe"
"email"
User's email address
Example: "john@example.com"
"roles"
User's permissions/roles
Example: ["admin", "user"]
"permissions"
Specific permissions
Example: ["read:posts", "write:posts"]
"tenant_id"
Multi-tenant identifier
Example: "company-abc"

Security Reminder

Never include sensitive information like passwords, social security numbers, or private keys in JWT payload. The payload is only Base64-encoded, not encrypted!

Common Debugging Scenarios

"Token Expired" Errors

When users get authentication failures, check the token expiration:

// Check exp claim
const now = Math.floor(Date.now() / 1000);
const isExpired = payload.exp < now;

Debug Steps:

  • 1. Decode the JWT to see the exp claim
  • 2. Convert Unix timestamp to readable date
  • 3. Compare with current time
  • 4. Check token refresh logic

Permission Debugging

When users can't access resources, check roles and permissions:

// Check roles in payload
const userRoles = payload.roles || [];
const hasAdminRole = userRoles.includes('admin');

Debug Steps:

  • 1. Decode JWT and examine roles claim
  • 2. Check permissions array if present
  • 3. Verify role-to-permission mapping
  • 4. Test with different user accounts

Invalid Signature

When signature verification fails:

// Common causes:
- Wrong secret key
- Token was modified
- Different algorithm used

Debug Steps:

  • 1. Verify the signing algorithm in header
  • 2. Check if secret key matches
  • 3. Ensure token wasn't tampered with
  • 4. Validate key rotation timing

Malformed Token

When token structure is invalid:

// Valid JWT structure:
header.payload.signature
// Must have exactly 3 parts

Debug Steps:

  • 1. Count dots (.) - should be exactly 2
  • 2. Check for truncated tokens
  • 3. Verify Base64 encoding
  • 4. Test with a known good token

Security Best Practices

Security Do's

  • •
    Use HTTPS - Always transmit JWTs over encrypted connections
  • •
    Short expiration times - Use 15-60 minutes for access tokens
  • •
    Strong secrets - Use cryptographically secure random keys
  • •
    Validate all claims - Check iss, aud, exp on every request
  • •
    Use refresh tokens - Implement proper token refresh flow
  • •
    Store securely - Use secure, httpOnly cookies when possible

Security Don'ts

  • •
    Don't store sensitive data - Payload is readable by anyone
  • •
    Don't use weak secrets - Avoid predictable or short keys
  • •
    Don't skip signature verification - Always validate server-side
  • •
    Don't use "none" algorithm - Disabled unsigned tokens
  • •
    Don't store in localStorage - Vulnerable to XSS attacks
  • •
    Don't ignore expiration - Always check exp claim

Algorithm Security

Recommended

  • • HS256 - HMAC with SHA-256
  • • RS256 - RSA with SHA-256
  • • ES256 - ECDSA with SHA-256

Deprecated

  • • HS1 - Weak hash function
  • • RS1 - Vulnerable to attacks
  • • Custom algorithms

Never Use

  • • none - No signature
  • • HS0 - No security
  • • MD5-based algorithms

Common Issues & Solutions

Clock Skew Issues

Problem:

Server and client clocks are out of sync, causing premature token expiration.

Solution:

  • • Add clock skew tolerance (usually 5 minutes)
  • • Use NTP to sync server clocks
  • • Implement proper time validation

Token Refresh Problems

Problem:

Users get logged out frequently due to short token lifetimes.

Solution:

  • • Implement refresh token flow
  • • Auto-refresh before expiration
  • • Use sliding expiration windows

Mobile App Considerations

Challenges:

  • • App backgrounding affects timers
  • • Network connectivity issues
  • • Secure storage limitations

Best Practices:

  • • Use device keychain/keystore
  • • Implement offline token validation
  • • Handle app lifecycle events

Testing Your JWT Implementation

Test Cases:

  • • Valid token acceptance
  • • Expired token rejection
  • • Invalid signature detection
  • • Malformed token handling

Security Tests:

  • • Algorithm confusion attacks
  • • None algorithm bypass
  • • Key confusion attacks
  • • Token replay attacks

Tools:

Ready to Decode Your JWT Tokens?

Use our secure JWT decoder with claim validation, signature verification, and detailed token analysis.

Start Decoding JWT Tokens Now