calculator.dtJwtTitle
Detailed Guide Coming Soon
We're working on a comprehensive educational guide for the JWT Decoder & Expiry Calculator. Check back soon for step-by-step explanations, formulas, real-world examples, and expert tips.
The JWT Decoder & Expiry Calculator parses JSON Web Tokens (JWT, defined in RFC 7519) — the standard token format for stateless authentication in modern web APIs. It decodes the base64url-encoded header and payload, parses JSON claims, and analyzes time-based claims including expiration (exp), issued-at (iat), not-before (nbf), subject (sub), issuer (iss), and audience (aud). JWTs are used by OAuth2/OIDC providers (Auth0, Okta, AWS Cognito, Clerk, Firebase Auth, Supabase) and most modern session systems. A JWT consists of three base64url-encoded segments separated by periods: header.payload.signature. The header declares the signing algorithm (HS256, RS256, ES256 are common). The payload contains 'claims' — both standard claims (sub, exp, iat, nbf, iss, aud, jti) and custom application-specific data. The signature cryptographically binds header and payload using either an HMAC secret (HS256) or asymmetric key pair (RS256/ES256). The decoder shows header and payload contents but does NOT verify the signature — that requires the secret or public key and should always be done server-side before trusting any JWT. Understanding JWT structure is essential for debugging authentication issues, understanding what data flows between client and server, and verifying that tokens are properly formed. Common debugging scenarios: 'Why is my token rejected?' (usually expired or wrong audience), 'What user is this token for?' (check sub claim), 'When does this expire?' (exp claim), and 'What permissions does this user have?' (custom claims like roles, scopes, or permissions). This calculator handles the most common analyses: structure validation (3 parts, valid base64url), JSON parsing, expiration status (valid, expiring soon <7 days, expired), not-yet-valid handling (nbf in future), and human-readable display of all standard claims plus full header and payload JSON. The signature is shown but not verified — production verification should always use a JWT library (jsonwebtoken, jose, PyJWT, etc.) with the correct verification key.
JWT Token = base64url(JSON header) + '.' + base64url(JSON payload) + '.' + base64url(signature); Valid if (exp > now) AND (nbf <= now OR nbf undefined)
- 1Step 1 — Paste Your JWT Token: Copy the full token (typically a long string starting with 'eyJ' since 'eyJ' is the base64url encoding of '{"' that starts the JSON header). Tokens are usually 100-2000+ characters long depending on payload size.
- 2Step 2 — Token Structure Validation: Calculator splits the token on periods. A valid JWT has exactly 3 parts: header, payload, signature. If splits don't produce 3 parts, the token is malformed. Common causes: truncation during copy-paste, missing parts in API responses, or non-JWT tokens (some APIs use opaque tokens that aren't JWTs).
- 3Step 3 — Base64url Decoding: Each part is base64url-decoded. Base64url is a URL-safe variant of base64 that uses - and _ instead of + and / and omits padding (=). Modern browsers' atob() function handles base64 but requires conversion: - → +, _ → /, add padding. If decoding fails, token is corrupted.
- 4Step 4 — JSON Parsing: Decoded header and payload should be valid JSON objects. If JSON.parse fails, the token's contents are corrupted or this isn't a standard JWT. Some legacy systems use 'JWT-like' formats with binary or non-JSON content that won't decode here.
- 5Step 5 — Claim Extraction and Analysis: Calculator extracts standard claims (exp, iat, nbf, sub, iss, aud) and displays them in human-readable form. exp and iat are converted from Unix timestamps to dates. Custom claims are shown in the full payload JSON for inspection.
- 6Step 6 — Expiration Status Calculation: Current time (now) compared to exp claim. Status categories: VALID (exp > now + 7 days), EXPIRING SOON (exp > now but < 7 days), EXPIRED (exp < now, shows days ago), NOT YET VALID (nbf > now, token is for future use). Days remaining shown for context.
- 7Step 7 — Signature Display (NOT Verified): The third segment (signature) is shown but never verified by this tool. Verification requires the secret (for HMAC algorithms) or public key (for asymmetric algorithms) and should be done server-side using a proper JWT library. Never trust unverified JWT contents in production code.
Typical short-lived access token decoded successfully
This is the standard JWT.io example token. Header declares HS256 algorithm and JWT type. Payload has user info (sub, name) plus timing (iat, exp). The status will depend on current date relative to exp. The signature shown is a placeholder — real tokens have valid HMAC signatures computed with the issuer's secret.
Common debugging scenario — token rejected for being past expiration
Most authentication failures with valid-looking tokens are simply expiration. The calculator shows exactly how many days past expiry. To fix: refresh the token using the refresh_token endpoint (OAuth2) or re-authenticate. Production code should automatically refresh access tokens 5-10 minutes before exp to avoid race conditions.
Catches truncated or non-JWT tokens before further processing
Tokens copied incompletely or from APIs that return non-JWT formats (opaque tokens, plain JWE encrypted blobs) will fail validation. The calculator's error message guides users to check token integrity. Common causes: line wrapping during copy, partial response from API, or using opaque OAuth tokens (some Microsoft endpoints) which aren't JWTs.
Rare use case for time-delayed authorization
Some systems issue tokens that become valid at a future time (e.g., scheduled meeting access, time-locked content). nbf (not before) prevents premature use. Most JWT libraries respect nbf and reject tokens before this time. If you see this status, the token isn't broken — it's intentionally not yet valid.
Debugging authentication issues by inspecting token claims and expiration timing
Verifying OAuth2/OIDC tokens during integration with providers like Auth0, Okta, AWS Cognito, or Clerk
Understanding what user data is encoded in tokens received from third-party APIs
Building admin tools that need to inspect user session tokens for support purposes
Learning JWT structure for engineering interviews and security audits
| Claim | Name | Required | Purpose |
|---|---|---|---|
| iss | Issuer | Optional | Who issued the token (e.g., identity provider URL) |
| sub | Subject | Optional | Who the token is about (typically user ID) |
| aud | Audience | Optional | Who should accept the token (your API) |
| exp | Expiration | Recommended | When token becomes invalid |
| nbf | Not Before | Optional | When token becomes valid (future scheduling) |
| iat | Issued At | Recommended | When token was created |
| jti | JWT ID | Optional | Unique identifier for the token (for replay prevention) |
Is JWT decoding the same as verifying?
No. Decoding extracts the contents anyone can read — the header and payload are just base64url encoded, not encrypted. Verification cryptographically checks the signature using the secret (HMAC algorithms) or public key (RSA/ECDSA algorithms) to confirm the token wasn't tampered with. Always verify before trusting token contents in production. Decoders like this tool are for debugging, not authentication.
Where should I store JWTs in browser apps?
Use httpOnly secure cookies, not localStorage or sessionStorage. localStorage is vulnerable to XSS — any injected script can read all stored tokens and exfiltrate them. httpOnly cookies are not accessible to JavaScript and provide built-in CSRF protection when set to SameSite=Strict or SameSite=Lax. For mobile apps, use platform secure storage (iOS Keychain, Android Keystore).
How long should JWT expiration be?
Short-lived access tokens (15-60 minutes) paired with longer refresh tokens (days to weeks). Avoid tokens that don't expire — once issued, they cannot be revoked without maintaining a blacklist (which defeats the stateless benefit of JWTs). Common patterns: 15-min access + 30-day refresh for web apps; 1-hour access + 90-day refresh for mobile apps; 5-min access + token rotation for high-security applications.
What's the difference between JWT and OAuth2?
OAuth2 is an authorization protocol (how clients get permission); JWT is a token format. OAuth2 can use JWTs as access tokens (most common today) or opaque tokens (Microsoft's older flows). JWTs work outside OAuth2 too — for direct API authentication, magic links, password reset tokens. They're complementary technologies, not competitors.
Should I use HS256 or RS256?
RS256 (asymmetric RSA) for distributed systems where multiple services verify tokens — they can each have the public key, only the issuer needs the private key. HS256 (symmetric HMAC) for single-service applications where the same service issues and verifies — simpler key management. Most identity providers use RS256 by default. Algorithm choice is part of your security posture.
What's the maximum JWT size?
Technically unlimited, but practical limits apply. HTTP header limit (usually 8KB total) constrains tokens sent via Authorization header. Cookie size limit (~4KB per cookie) constrains storage. Most production JWTs are 500-2000 characters. If your JWT exceeds 4KB, you have too many custom claims — consider fetching user details from a database using just sub instead.
Pro Tip
Use refresh token rotation in production — every refresh issues a new pair and invalidates the old one. This limits the blast radius if a refresh token is stolen and detects token theft when a stolen old token attempts use after rotation. Major providers (Auth0, Okta, Cognito) support this pattern out of the box.
Did you know?
The JWT specification (RFC 7519) was finalized in May 2015 after several years of draft revisions. It evolved from earlier efforts including SWT (Simple Web Token) at Microsoft and JOSE (JSON Object Signing and Encryption) at the IETF. The 'eyJ' prefix that begins virtually every JWT is the base64url encoding of '{"' — the opening of any JSON object. This pattern makes JWTs visually identifiable at a glance.