JWT Decoder

Decode and Debug JSON Web Tokens

JWTs are those long cryptic strings APIs use for authentication. They look random but actually contain encoded JSON data about the user, expiration time, and permissions. This decoder shows you what's inside without needing to verify the signature—perfect for debugging auth issues.

How It Works

1. Paste the JWT token (looks like xxx.yyy.zzz with dots).
2. See the decoded header and payload as readable JSON.
3. Check expiration times, user IDs, or custom claims.

When You'd Use This

Debugging auth: Check if the token has correct user ID or permissions.

Expiration issues: See if token expired and that's why requests are failing.

Learning: Understand how JWTs structure data for API authentication.

Questions

Does this verify signatures?

No, it just decodes. Verification needs the secret key, which you shouldn't paste into random web tools. This shows you what's in the token, not whether it's valid.

Deep Dive into JWT Structure and Encoding

JSON Web Tokens follow a three-part structure separated by dots: header.payload.signature. Each section contains Base64URL-encoded JSON data (Base64 with URL-safe characters). The header typically specifies the token type ("JWT") and signing algorithm like HS256 (HMAC-SHA256), RS256 (RSA-SHA256), or ES256 (ECDSA-SHA256). Algorithm choice matters enormously for security - symmetric algorithms like HS256 use a shared secret for both signing and verification, while asymmetric algorithms like RS256 use public/private key pairs where the private key signs tokens and the public key verifies them. Asymmetric algorithms enable scenarios where many services verify tokens but only one authentication server creates them.

The payload contains claims - statements about the user and token metadata. Standard claims include "iss" (issuer), "sub" (subject/user ID), "aud" (audience), "exp" (expiration timestamp), "nbf" (not before timestamp), and "iat" (issued at timestamp). Custom claims hold application-specific data like user roles, permissions, or preferences. Keep payloads small since JWTs transmit with every request - large tokens increase bandwidth consumption and latency. Never include sensitive information like passwords, credit card numbers, or personal identifiable information in JWT payloads because they're only Base64-encoded, not encrypted. Anyone who intercepts a JWT can decode and read the payload using tools exactly like this one.

JWT Authentication Flow in Modern Web Applications

When users log in, the authentication server validates their credentials, creates a JWT containing their user ID and permissions, signs it with a secret key or private key, and returns the token to the client. The client stores this JWT (typically in memory, localStorage, or httpOnly cookies) and includes it in the Authorization header of subsequent API requests using the Bearer scheme: "Authorization: Bearer eyJhbGci...". The API server receives each request, extracts the JWT from the header, verifies the signature using the secret key or public key, and checks the expiration timestamp. If verification succeeds and the token hasn't expired, the server trusts the claims in the payload and processes the request according to the user's permissions.

This stateless authentication approach offers significant architectural advantages. Servers don't need to maintain session storage or query databases to validate every request - the JWT itself contains all necessary information. This makes horizontal scaling trivial since any server can validate any JWT without shared state. Microservices architectures benefit enormously because services can verify tokens independently without calling back to a central authentication service for every request. The signature ensures tokens can't be tampered with - changing any character in the header or payload invalidates the signature, causing verification to fail. However, JWTs can't be easily revoked once issued. If a JWT leaks, it remains valid until expiration. Many systems implement token blacklists or short expiration times (15 minutes) with refresh tokens to mitigate this limitation.

Common JWT Security Vulnerabilities and Prevention

The "alg: none" attack exploits poorly implemented JWT libraries that accept unsigned tokens when the header specifies "alg": "none". Attackers modify the payload to escalate privileges or impersonate users, remove the signature entirely, and change the algorithm to "none". Vulnerable servers accept these tampered tokens as valid. Prevention requires strict validation that rejects "none" algorithm tokens unless explicitly intended for public data. Another vulnerability involves algorithm confusion attacks where attackers change RS256 (asymmetric) to HS256 (symmetric) in the header. If the server uses the public key as an HMAC secret to verify the forged HS256 token, verification succeeds despite the attacker creating the signature themselves. Proper implementations specify allowed algorithms explicitly rather than trusting the header's algorithm claim.

JWT injection attacks exploit applications that trust decoded JWT data without proper validation. Never use JWT claims for SQL queries, file paths, or shell commands without sanitization. Treat JWT data like any user input - validate, sanitize, and use parameterized queries or prepared statements. Cross-site scripting (XSS) attacks can steal JWTs stored in localStorage since JavaScript can access it. Consider httpOnly cookies for storage, which JavaScript cannot read, though this introduces CSRF vulnerabilities requiring additional protection. Always transmit JWTs over HTTPS only - tokens sent over unencrypted HTTP are trivially intercepted. Implement short expiration times and refresh token rotation to minimize the window of opportunity if tokens leak. Monitor for unusual patterns like tokens used from multiple IP addresses simultaneously or unusual geographic locations.

JWT Claims: Standard and Custom

Registered claims defined by RFC 7519 provide standard fields for common use cases. The "iss" (issuer) claim identifies who created the token, enabling multi-tenant systems where different authentication servers issue tokens. The "aud" (audience) claim specifies intended recipients, allowing services to reject tokens meant for different applications. The "exp" (expiration) claim contains a Unix timestamp when the token becomes invalid - servers must reject expired tokens to prevent indefinite token validity. The "nbf" (not before) claim enables future-dated tokens that become valid only after a specific time. The "jti" (JWT ID) claim provides a unique identifier for each token, useful for tracking or blacklisting specific tokens.

Custom claims hold application-specific data but require careful design. Avoid claim name collisions with standard claims by using namespaced keys like "app:role" or "company.com/permissions". Keep custom claims minimal since JWT size affects every request's bandwidth and latency. Consider whether data should live in the JWT or be fetched separately - frequently changing data belongs in databases, not JWTs, since tokens can't be updated without reissuing. Good candidates for custom claims include user roles, subscription tier, feature flags, or preferences that change infrequently and must be checked on every request. Bad candidates include user profiles, preferences that update often, or large datasets that bloat token size unnecessarily.

JWT vs Session Cookies: Trade-offs and Use Cases

Traditional session-based authentication stores session data on the server (in memory, Redis, or databases) and sends only a session ID cookie to clients. This enables instant revocation - deleting the server-side session immediately logs out the user. Sessions work well for monolithic applications with shared session storage but complicate distributed systems requiring session replication or sticky load balancing. JWTs eliminate server-side state entirely, enabling stateless authentication that scales horizontally without session synchronization. However, JWTs cannot be revoked instantly - once issued, they remain valid until expiration unless complex blacklist systems are implemented.

Choose sessions when immediate revocation matters (banking applications, admin panels), when session data changes frequently, or when the application is monolithic. Choose JWTs for microservices architectures, mobile applications that work offline periodically, or systems requiring authentication across multiple domains. Hybrid approaches combine both: short-lived JWTs (15 minutes) for API requests plus longer-lived refresh tokens (7 days) stored as httpOnly cookies. When the JWT expires, clients use the refresh token to obtain a new JWT. This balances stateless performance for most requests with the ability to revoke refresh tokens when needed. The refresh token validation can check a database or cache for revocations without impacting every API call.

Implementing JWT Best Practices

Always validate tokens server-side - never trust client-side validation alone. Verify the signature using the correct algorithm and key, check the expiration timestamp against current time (with small clock skew allowance, typically 60 seconds), validate the issuer matches your authentication server, and confirm the audience includes your service. Reject tokens with missing required claims, invalid signature, expired timestamps, or unexpected issuers. Use established JWT libraries (jose, jsonwebtoken, PyJWT) rather than implementing verification manually - subtle bugs in custom implementations lead to security vulnerabilities.

Store secrets securely - never hardcode signing keys in source code or commit them to version control. Use environment variables, key management services (AWS KMS, Azure Key Vault), or secure secret stores. Rotate signing keys periodically to limit impact if keys leak. Support multiple active keys simultaneously during rotation - sign new tokens with the new key while still accepting tokens signed with the old key during a transition period. Implement proper error handling that doesn't leak information - return generic "unauthorized" errors rather than specific validation failure reasons that help attackers. Log JWT validation failures for security monitoring and anomaly detection. Rate limit authentication endpoints to prevent brute force attacks on tokens or credentials.

Advanced JWT Questions

Can I modify a JWT and re-sign it?

Only if you have the signing secret (for HS256/HS512) or private key (for RS256/ES256). Servers verify signatures using the secret or public key, so tampering with header or payload invalidates the signature. This cryptographic guarantee prevents clients from modifying their tokens to escalate privileges or forge identities. If you need to update claims, the proper approach is requesting a new token from the authentication server.

What happens if the JWT is too large?

Large JWTs impact performance since they transmit with every request. HTTP headers are typically limited to 8KB across all headers combined, and individual headers may have lower limits. Extremely large JWTs might exceed these limits, causing request failures. Keep JWTs under 1-2KB ideally. If you need more data, reference it by ID in the JWT and fetch it separately rather than embedding large objects directly in tokens.

Should I store JWTs in localStorage or cookies?

Both have trade-offs. LocalStorage is vulnerable to XSS attacks since JavaScript can access it. HttpOnly cookies are immune to XSS but require CSRF protection. Current best practice for maximum security: store short-lived access tokens in memory (lost on page refresh) and httpOnly refresh tokens in cookies. When the page loads or access token expires, use the refresh token to get a new access token. This combines security with usability.

How do I invalidate a specific JWT?

JWTs are stateless by design, so invalidation requires additional infrastructure. Common approaches include maintaining a blacklist of revoked token IDs (jti claim) in Redis or a database that verification checks before accepting tokens. Alternatively, use short expiration times (5-15 minutes) so compromised tokens expire quickly. Refresh tokens, stored server-side or with revocation checking, provide new access tokens. When you need to revoke access, block the refresh token - the short-lived access token expires soon after.

What's the difference between access tokens and refresh tokens?

Access tokens are short-lived JWTs (minutes to hours) used for API requests. They contain user permissions and identity. Refresh tokens are long-lived credentials (days to months) used only to obtain new access tokens when they expire. Refresh tokens typically use opaque identifiers stored in databases, enabling revocation. This separation balances security (short-lived credentials) with user experience (no frequent re-authentication). If an access token leaks, it expires quickly. If a refresh token leaks, you can revoke it immediately.

Can I use JWTs for email verification links?

Yes, JWTs work well for email verification, password reset tokens, and other one-time-use scenarios. Include claims for the user ID, action type, and short expiration (typically 1-24 hours). The email contains a link with the JWT as a query parameter. When users click it, your server verifies the signature and expiration, processes the action (verify email, reset password), then invalidates that specific JWT to prevent reuse. Store used token IDs (jti) in a blacklist or track completion in your database.

Debugging JWT Issues

• Check expiration: Use this decoder to view the "exp" claim and convert the Unix timestamp to verify the token hasn't expired.
• Verify structure: Ensure the token has exactly three parts separated by dots. Missing or extra dots indicate malformed tokens.
• Validate claims: Confirm required claims like sub, iss, or custom claims contain expected values.
• Inspect algorithm: Check the header's "alg" claim matches what your server expects. Mismatches cause verification failures.
• Test in isolation: Decode tokens outside your application to determine if issues stem from token content or application logic.
• Compare tokens: Decode working and failing tokens side-by-side to identify differences causing authentication problems.

Related Tools

✓ Base64 Encoder - Encode and decode Base64 data
✓ JSON Formatter - Format and validate JSON
✓ Hash Generator - Generate cryptographic hashes
✓ UUID Generator - Create unique identifiers