JWT Decoder

{}

{}

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  your-256-bit-secret
)

Waiting for token input...

A JWT (JSON Web Token) is a compact, URL-safe token used for authentication and API authorization. It consists of three Base64Url-encoded parts separated by dots — a header (signing algorithm), a payload (claims like user ID and expiry), and a signature (integrity proof). To decode a JWT online: paste the token into the input above and the tool instantly displays all three parts, highlights expiry status, and validates claims. Unlike most JWT debuggers, bitlist decodes entirely in your browser — no server request is made, making it safe to use with real production tokens.

Free Secure JWT Decoder & Verifier (Client-Side Only)

Bitlist's JWT Debugger is the safest way to decode and inspect JSON Web Tokens directly in your browser. Designed for privacy-conscious developers, our tool ensures that your sensitive tokens—and the secrets they contain—never leave your device.

Why Debug JWTs Locally?

Many online JWT checkers send your data to a backend server for processing. This creates a security risk if you are debugging production tokens or tokens containing sensitive user data (PII).

• 100% Private: Logic runs via JavaScript in Chrome/Firefox/Safari. No server logging.
• Instant & Offline: Works without an internet connection once loaded.
• RFC 7519 Compliant: Accurately parses headers, payloads, and signatures according to the official standard.

JWT Structure Overview

A JWT is composed of three Base64Url-encoded parts separated by dots: header, payload, and signature. The header describes the algorithm, the payload holds claims, and the signature validates integrity.

Common Use Cases

• Debugging authentication failures in staging or production.
• Verifying claim values during authorization checks.
• Comparing tokens before and after a refresh flow.

Features

• Color-Coded Segments: Instantly visualize the three parts of a JWT: Header (Algorithm), Payload (Data), and Signature.
• Local HMAC Verification: Verify HS256/HS384/HS512 signatures in-browser with your secret key.
• Claim Health Checks: Review exp, nbf, and iat status instantly.
• Error Validation: Get immediate feedback if your token is malformed or invalid.
• Pretty Print: Automatically formats minified JSON into readable, indented code.

Example JWT Breakdown

Header

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

Payload

{"sub":"user-123","role":"admin","exp":1800000000}

Signature

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

Claim Tips

• exp: Expiration time. Validate it against current UTC time.
• nbf: Not before. Tokens are invalid before this timestamp.
• iat: Issued at. Helpful for debugging token freshness.
• aud/iss: Confirm the audience and issuer match your service.

Suggested Workflow

1. Paste the token and confirm it splits into three segments.
2. Inspect header and payload for expected values.
3. Verify signature if you have the HMAC secret.
4. Check exp, nbf, and iat to ensure token validity.

Security Best Practices

• Never share production secrets in public or shared environments.
• Rotate tokens frequently when debugging sensitive systems.
• Validate issuer and audience to prevent token misuse.

Algorithm Notes

HMAC tokens (HS256/HS384/HS512) use a shared secret and can be verified locally. RSA or ECDSA tokens require public keys and are commonly used in distributed systems.

Troubleshooting

• Token has fewer than three segments: A valid JWT must have header, payload, and signature.
• Signature verification fails: Double-check the secret and algorithm.
• Claims look wrong: Confirm your app uses Base64Url, not standard Base64.

Frequently Asked Questions

Understanding JWT Components in Depth

Header Structure

The JWT header defines the token type and signing algorithm. Standard fields include alg (algorithm: HS256, RS256, ES256, etc.) and typ (typically "JWT"). Additional fields like kid (Key ID) help identify which key signed the token in systems with key rotation.

Example: {"alg": "RS256", "typ": "JWT", "kid": "key-2024-01"} indicates RSA-SHA256 signing with key identifier "key-2024-01".

Payload Claims

JWT payloads contain claims—statements about an entity (user) and additional data. Three types exist:

• Registered claims: Predefined by RFC 7519 (iss, sub, aud, exp, nbf, iat, jti).
• Public claims: Custom claims registered in IANA JWT Registry or using collision-resistant names.
• Private claims: Custom claims agreed upon between parties (roles, permissions, user data).

Key registered claims:

• iss (Issuer): Who created the token (auth.example.com).
• sub (Subject): Who the token is about (user ID: "user-123").
• aud (Audience): Who should accept this token (api.example.com).
• exp (Expiration): Unix timestamp when token expires (1735689600).
• nbf (Not Before): Unix timestamp before which token is invalid.
• iat (Issued At): Unix timestamp when token was created.
• jti (JWT ID): Unique identifier for token (prevents replay attacks).

Signature Verification

The signature ensures token integrity—verifying it wasn't tampered with. Calculated by encoding header and payload, then signing with a secret (HMAC) or private key (RSA/ECDSA).

HMAC (HS256/HS384/HS512): Symmetric signing using shared secret. Both issuer and verifier know the same secret. Fast but requires secure secret distribution.

RSA (RS256/RS384/RS512): Asymmetric signing. Issuer signs with private key, verifiers use public key. Suitable for distributed systems where multiple services verify tokens.

ECDSA (ES256/ES384/ES512): Elliptic curve asymmetric signing. Smaller keys than RSA with equivalent security. Growing popularity for performance-critical systems.

Common JWT Use Cases

1. Stateless Authentication

User logs in, server issues JWT containing user ID and permissions. Subsequent API requests include JWT in Authorization header. Server verifies signature and extracts user info without database lookups. Scales horizontally since no session storage needed.

2. Single Sign-On (SSO)

User authenticates with identity provider (Okta, Auth0, Azure AD), receives JWT. JWT is accepted by multiple services within organization. Each service verifies JWT independently using shared public key or HMAC secret.

3. API Authorization

OAuth 2.0 access tokens often use JWT format. Scopes and permissions encoded in token. API gateways verify JWT and enforce authorization policies based on claims. Fine-grained access control without database queries.

4. Information Exchange

Securely transmit information between parties with signature verification. Microservices pass user context via JWTs. Each service verifies signature to ensure data integrity and authenticity.

Best Practices for JWT Implementation

• Keep tokens short-lived: Set exp claim to 15-60 minutes for access tokens. Use refresh tokens for longer sessions. Short expiry limits damage from token theft.
• Use strong secrets: HMAC secrets should be 256+ bits (32+ random characters). Use cryptographically secure random generators, not passwords.
• Always verify signatures: Never trust decoded payload without signature verification. Attackers can modify payload if signature isn't checked.
• Validate all claims: Check exp (not expired), nbf (not used too early), iss (expected issuer), aud (intended audience). Reject tokens failing any check.
• Use HTTPS only: JWTs in Authorization headers travel over network. Without HTTPS, tokens can be intercepted (man-in-the-middle attacks).
• Store securely: In browsers, use httpOnly cookies (not localStorage) to prevent XSS attacks from stealing tokens.
• Implement token revocation: Maintain deny-list for compromised tokens or use short expiry + refresh token pattern.
• Don't store sensitive data: JWTs are encoded, not encrypted. Anyone with the token can decode and read payload. Store only non-sensitive identifiers.
• Rotate signing keys: Use kid header to identify keys. Rotate keys regularly (quarterly/annually). Support overlapping key validity for smooth transitions.
• Set appropriate aud/iss: Prevent token misuse by validating audience and issuer. Reject tokens not intended for your service.

Security Considerations and Vulnerabilities

Algorithm Confusion (alg: none)

Vulnerability: Attackers change alg to "none", remove signature, and some libraries accept unsigned tokens.

Mitigation: Explicitly reject alg: none. Specify allowed algorithms in verification code. Never use algorithm from header without validation.

Algorithm Substitution (HMAC → RSA)

Vulnerability: If system expects RS256 (RSA) but accepts HS256 (HMAC), attacker uses public key as HMAC secret to forge tokens.

Mitigation: Enforce strict algorithm checks. Never allow algorithm switching based on header alone.

Token Replay Attacks

Vulnerability: Stolen valid tokens can be reused until expiration.

Mitigation: Short expiry times (15-60 min). Use jti (JWT ID) with one-time-use tracking for critical operations. Implement token binding to client IP or device fingerprint (with privacy considerations).

Information Disclosure

Vulnerability: Sensitive data in payload is visible to anyone with the token (encoding ≠ encryption).

Mitigation: Store only non-sensitive identifiers (user ID, roles). Use encrypted JWTs (JWE - JSON Web Encryption) for sensitive data. Keep tokens in httpOnly cookies to prevent JavaScript access.

Cross-Site Scripting (XSS)

Vulnerability: XSS attacks can steal JWTs from localStorage or sessionStorage.

Mitigation: Store tokens in httpOnly, Secure, SameSite cookies. Never access tokens via JavaScript if possible. Implement Content Security Policy (CSP). Sanitize all user input.

Cross-Site Request Forgery (CSRF)

Vulnerability: If using cookies, CSRF attacks can use victim's session to make unauthorized requests.

Mitigation: Use SameSite=Strict or SameSite=Lax cookies. Implement CSRF tokens for state-changing operations. Verify Origin/Referer headers.

Troubleshooting Common JWT Issues

Issue: "Token Expired" Errors

Cause: exp claim is in the past. Clock skew between issuer and verifier can cause premature expiry.

Solution: Implement clock skew tolerance (accept tokens expiring within 1-2 minutes grace period). Ensure NTP (Network Time Protocol) sync on all servers. Implement token refresh flow before expiry.

Issue: Signature Verification Fails

Causes: Wrong secret, algorithm mismatch (HS256 vs RS256), key ID mismatch (kid), line breaks/whitespace in secret, or tampered token.

Solution: Verify exact secret string (no extra spaces). Confirm algorithm matches header alg. Check kid matches key used for signing. Log signature verification failures with details for debugging.

Issue: Invalid Token Format

Causes: Missing dots (not 3 parts), invalid Base64Url encoding, truncated token, or extra characters.

Solution: Verify token has exactly 3 parts separated by dots: header.payload.signature. Check for accidental whitespace or newlines. Ensure proper Base64Url encoding (- and _ instead of + and /).

Issue: Claims Don't Match Expectations

Causes: aud doesn't match your service, iss is unknown, sub format differs from expected, or custom claims missing.

Solution: Log actual vs expected claim values. Verify issuer configuration. Check token is intended for your service (aud claim). Coordinate claim naming with token issuer.

Issue: Token Too Large (Cookie Overflow)

Cause: Including too much data in payload. Cookies have 4KB limit. Large payloads slow network and increase bandwidth.

Solution: Store only essential identifiers (user ID, session ID). Fetch additional user data from database using ID. Use opaque reference tokens for cookie storage, JWT for Authorization header.

Advanced JWT Features

Refresh Tokens

Issue short-lived access tokens (15 min) with long-lived refresh tokens (7-30 days). When access token expires, client uses refresh token to obtain new access token without re-authentication. Store refresh tokens securely (httpOnly cookie, database with revocation).

Token Rotation

With each refresh, issue both new access token and new refresh token. Invalidate old refresh token. Limits damage if refresh token is stolen—only valid until next rotation.

Nested JWTs (JWT in JWT)

Outer JWT provides encryption (JWE), inner JWT provides signing (JWS). Combines confidentiality and integrity. Useful for sensitive data requiring both encryption and signature verification.

JSON Web Encryption (JWE)

Encrypts JWT payload for confidentiality. Five parts: header, encrypted key, initialization vector, ciphertext, authentication tag. Prevents payload inspection by unauthorized parties. More complex than JWS but necessary for sensitive data.

Enhanced Frequently Asked Questions

What's the difference between encoding and encrypting a JWT?

Encoding (Base64Url): JWTs are Base64Url encoded, not encrypted. Anyone can decode and read the payload—it's just obfuscation, not security. Use atob() in JavaScript or any Base64 decoder to read payload without signature verification. Encryption (JWE): Encrypted JWTs (JWE) use cryptographic encryption so only parties with the decryption key can read payload content. Standard JWTs (JWS) are signed for integrity but not encrypted for confidentiality.

Should I use JWTs for session management?

Pros: Stateless (no server-side session storage), scalable (no shared session database), portable (works across services). Cons: Can't invalidate before expiry (logout requires deny-list or short expiry), payload size increases bandwidth, sensitive data visible if not encrypted. Recommendation: Use JWTs for stateless APIs and microservices. For traditional web apps with sensitive sessions, consider opaque session tokens with server-side storage or hybrid approach (JWT + session).

How do I revoke a JWT before expiration?

JWTs are stateless—once issued, they're valid until expiry. Solutions: (1) Short expiry times (15-60 min) minimize revocation window. (2) Maintain deny-list (blacklist) of revoked token IDs (jti claim) in Redis or database. (3) Use refresh token pattern—revoke refresh token to prevent new access tokens. (4) Include version claim—increment on logout, reject older versions. (5) Use opaque tokens instead if immediate revocation is critical.

Can I decode a JWT without the secret?

Yes. JWTs are Base64Url encoded, not encrypted. Anyone can decode header and payload without the secret using Base64 decoding. The secret is only needed for signature verification—to confirm the token hasn't been tampered with. This is why you should never put sensitive information (passwords, credit cards, SSNs) in JWT payload. Use only non-sensitive identifiers and fetch sensitive data from database after verification.

What's the maximum JWT size?

Technical limit: No hard limit in specification. Practical limits: HTTP headers are typically limited to 8KB by web servers. Cookies are limited to 4KB per cookie. URL length limits (2KB in IE, 8KB in modern browsers) affect JWTs in query parameters. Recommendation: Keep JWTs under 1KB for optimal performance. Large payloads increase bandwidth, slow parsing, and may hit server limits. Store only essential claims (user ID, roles, expiry), fetch details from database.

Which algorithm should I use: HS256, RS256, or ES256?

HS256 (HMAC + SHA-256): Symmetric secret. Fast. Use for single service or tightly coupled services sharing secrets. Risk: compromised secret means attacker can forge tokens. RS256 (RSA + SHA-256): Asymmetric keys. Issuer signs with private key, verifiers use public key. Use for distributed systems, SSO, or when multiple services verify tokens. Larger signatures, slower than HMAC. ES256 (ECDSA + SHA-256): Asymmetric elliptic curve. Smaller keys/signatures than RSA with equivalent security. Faster than RSA. Growing adoption, best balance of security and performance for distributed systems.

How do I test JWT verification in my application?

Testing approach: (1) Valid token: Test with correctly signed token, verify acceptance. (2) Expired token: Test with exp in past, verify rejection. (3) Invalid signature: Modify payload, verify rejection. (4) Wrong algorithm: Test with different algorithm than expected, verify rejection. (5) alg: none attack: Test with alg: none header, verify rejection. (6) Wrong audience: Test with different aud claim, verify rejection. (7) nbf future: Test with nbf in future, verify rejection. Tools: Use this decoder to generate test tokens. Libraries: jsonwebtoken (Node.js), PyJWT (Python), jose4j (Java) for test token generation.

What's the difference between JWT and OAuth 2.0?

JWT: A token format specification (RFC 7519) defining how to structure and sign JSON data. OAuth 2.0: An authorization framework (RFC 6749) defining flows for obtaining access tokens. Relationship: OAuth 2.0 can use JWT as the token format for access tokens (but can also use opaque tokens). OAuth 2.0 defines how to get tokens, JWT defines what the token looks like. Many modern OAuth 2.0 implementations (like OpenID Connect) use JWTs for access tokens and ID tokens.

Can I use JWTs for password reset tokens?

Possible but not recommended. Problems: (1) JWTs can't be revoked before expiry—if user requests multiple resets, old tokens remain valid. (2) If secret leaks, attacker can forge reset tokens. (3) Long expiry times (1-24 hours) increase risk window. Better approach: Generate random token (UUID), store in database with user ID and expiry, send in email. Verify token exists in database before allowing password reset, then delete token. This allows immediate revocation and simpler security model for sensitive operations.

How do public key servers (JWKS) work?

JWKS (JSON Web Key Set): Public endpoint exposing cryptographic keys for JWT verification. Flow: (1) Issuer publishes public keys at /.well-known/jwks.json. (2) JWT header includes kid (Key ID) identifying which key signed the token. (3) Verifier fetches JWKS, finds key matching kid, uses public key to verify signature. Benefits: Key rotation without updating all services, supports multiple concurrent keys, enables distributed verification. Example: Auth0, Okta, Azure AD use JWKS for SSO systems.

Are JWTs vulnerable to replay attacks?

Yes, if stolen. Attack: Attacker intercepts valid JWT, replays it to gain unauthorized access. Mitigations: (1) HTTPS only—prevents interception. (2) Short expiry (15-60 min)—limits replay window. (3) Token binding—bind JWT to client IP, device fingerprint, or TLS certificate (with privacy trade-offs). (4) One-time tokens—use jti claim with one-time-use tracking for critical operations (password changes, financial transactions). (5) Nonce—include nonce in payload, reject duplicate nonces. Complete prevention requires server-side state, which defeats JWT statelessness.