JWT Debugger

---

name: jwt-debugger description: Decode, validate, and debug JSON Web Tokens. Inspect headers, payloads, signatures, expiration, claims, and key mismatches. Diagnose common JWT issues in authentication flows without external tools.

---

JWT Debugger

Decode and debug JWTs without pasting them into random websites. Inspect headers, validate signatures, check expiration and claims, diagnose key mismatches, and trace authentication failures — all locally, keeping tokens secure.

Use when: "debug jwt", "decode this token", "why is auth failing", "jwt expired", "invalid signature", "token validation error", "check jwt claims", or when troubleshooting authentication.

Commands

1. decode — Decode and Inspect JWT

# Decode without signature verification (inspection only)
echo "$TOKEN" | python3 -c "
import sys, json, base64
token = sys.stdin.read().strip()
parts = token.split('.')
if len(parts) != 3:
    print(f'❌ Invalid JWT: expected 3 parts, got {len(parts)}')
    sys.exit(1)
def decode_part(s):
    padding = 4 - len(s) % 4
    s += '=' * padding
    return json.loads(base64.urlsafe_b64decode(s))
header = decode_part(parts[0])
payload = decode_part(parts[1])
print('=== HEADER ===')
print(json.dumps(header, indent=2))
print()
print('=== PAYLOAD ===')
print(json.dumps(payload, indent=2))
print()
Check expiration
import time
if 'exp' in payload:
    exp = payload['exp']
    now = int(time.time())
    remaining = exp - now
    if remaining < 0:
        print(f'🔴 EXPIRED: {abs(remaining)//3600}h {abs(remaining)%3600//60}m ago')
    elif remaining < 300:
        print(f'🟡 EXPIRING SOON: {remaining}s remaining')
    else:
        print(f'🟢 Valid: {remaining//3600}h {remaining%3600//60}m remaining')
if 'iat' in payload:
    from datetime import datetime, timezone
    issued = datetime.fromtimestamp(payload['iat'], tz=timezone.utc)
    print(f'Issued at: {issued.isoformat()}')
if 'nbf' in payload:
    nbf = payload['nbf']
    now = int(time.time())
    if now < nbf:
        print(f'🔴 NOT YET VALID: becomes valid in {nbf - now}s')
Common claims
for claim, label in [('sub', 'Subject'), ('iss', 'Issuer'), ('aud', 'Audience'), ('scope', 'Scopes'), ('roles', 'Roles')]:
    if claim in payload:
        print(f'{label}: {payload[claim]}')
print(f'\\nAlgorithm: {header.get(\"alg\", \"MISSING\")}')
print(f'Key ID: {header.get(\"kid\", \"not set\")}')
print(f'Type: {header.get(\"typ\", \"not set\")}')
"

2. validate — Full Signature Verification

# Verify with known secret (HS256)
python3 -c "
import sys, hmac, hashlib, base64
token = '$TOKEN'
secret = '$SECRET'
parts = token.split('.')
signing_input = f'{parts[0]}.{parts[1]}'.encode()
signature = base64.urlsafe_b64decode(parts[2] + '==')
expected = hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
if hmac.compare_digest(signature, expected):
    print('✅ Signature VALID')
else:
    print('❌ Signature INVALID — secret mismatch or token tampered')
"
Verify with public key (RS256/ES256)
python3 -c "
import jwt  # pip install PyJWT[crypto]
try:
    decoded = jwt.decode('$TOKEN', '$PUBLIC_KEY', algorithms=['RS256'], audience='$EXPECTED_AUD')
    print('✅ Valid:', decoded)
except jwt.ExpiredSignatureError:
    print('❌ Token expired')
except jwt.InvalidSignatureError:
    print('❌ Invalid signature — wrong key or tampered token')
except jwt.InvalidAudienceError:
    print('❌ Audience mismatch')
except Exception as e:
    print(f'❌ {e}')
"

3. diagnose — Common JWT Problems

Check for these issues:

Expiration issues:

Token expired → check clock sync between issuer and validator

Token not yet valid (nbf) → clock skew between services

Very short TTL (< 5 min) → may cause issues with slow requests

Signature issues:

"none" algorithm → security vulnerability, reject immediately

Algorithm mismatch → server expects RS256, token has HS256

Wrong key → key rotation happened, old key used

kid mismatch → key ID in header doesn't match available keys

Claims issues:

Missing required claims (iss, sub, aud, exp)

Audience mismatch → token issued for service A, used with service B

Issuer mismatch → token from wrong identity provider

Scope insufficient → token has read scope, endpoint requires write

Security red flags:

alg: "none" → algorithm confusion attack

alg: "HS256" with RSA public key → key confusion attack

Token in URL query parameter → logged in server logs, browser history

Token size > 8KB → may exceed header size limits

Sensitive data in payload (passwords, SSN) → payload is base64, not encrypted

# JWT Diagnostic Report
Token Summary
Algorithm: RS256
Issuer: auth.example.com
Subject: user-12345
Issued: 2026-04-29 01:00:00 UTC
Expires: 2026-04-29 02:00:00 UTC (🔴 EXPIRED 31m ago)
Issues Found
1. 🔴 Expired — token expired 31 minutes ago
   Fix: refresh token or re-authenticate
2. 🟡 No audience claim — token doesn't specify intended audience
   Risk: token accepted by unintended services
   Fix: add aud claim to token issuer config
3. 🟢 Algorithm: RS256 (secure)
4. 🟢 Key ID present: matches current JWKS

4. compare — Diff Two Tokens

Compare tokens side-by-side to identify what changed:

Different claims (permissions changed?)

Different expiry (session settings changed?)

Different issuer (wrong auth provider?)

Different kid (key rotated?)

5. generate — Create Test JWT

Generate a signed JWT for testing:

python3 -c "
import jwt, time, json
payload = {
    'sub': 'test-user',
    'iss': 'test-issuer',
    'aud': 'test-audience',
    'iat': int(time.time()),
    'exp': int(time.time()) + 3600,
    'scope': 'read write'
}
token = jwt.encode(payload, 'test-secret', algorithm='HS256')
print(token)
"