JWT Decoder

Complete Guide to JWT Decoding, Claims, and OAuth Token Inspection

JSON Web Tokens (JWTs) power authentication and authorization across modern web applications. OpenID Connect identity layers, OAuth 2.0 access tokens, microservice session cookies, and single sign-on portals all serialize identity and permission data into compact, URL-safe strings that clients attach to API requests. A JWT looks opaque at first glance — three Base64URL-encoded segments separated by dots — but the header and payload are only encoded, not encrypted. Understanding how to decode and read JWT claims is essential for debugging login failures, verifying token expiry, and auditing what your applications expose to browsers and mobile clients.

ToolsFree.org provides a fast, privacy-focused JWT decoder that parses tokens entirely in your browser. Paste a JWT to inspect its header and payload JSON, view standard claims like exp and iat, and understand structure without sending tokens to a server. This page explains JWT anatomy, OAuth relationships, claim semantics, and safe debugging practices — not signature verification against secrets, which must remain on trusted servers.

What Is a JSON Web Token?

A JWT is a compact serialization format defined in RFC 7519. It consists of three parts: header, payload, and signature, joined by periods (.). The header typically declares the signing algorithm (alg) and token type (typ, usually JWT). The payload contains claims — JSON key-value pairs asserting facts about the subject, issuer, audience, and validity window. The signature proves integrity: only parties holding the secret or private key could have produced a valid signature for that header and payload.

Encoding uses Base64URL, a URL-safe variant without padding that replaces + and / with - and _. Decoding is reversible with standard libraries — which means anyone who possesses the token string can read the payload. Never put confidential data in JWT payloads unless you additionally encrypt the token (JWE) or accept that the data is visible to the client.

How to Use This JWT Decoder Step by Step

Paste the complete JWT string into the input field — all three segments, including dots. The tool decodes the header and payload into formatted JSON for inspection. Review the alg field first: unexpected algorithms (especially none or asymmetric algorithms you did not configure) can indicate misconfiguration or attack attempts in poorly validated servers.

Check temporal claims next. Compare exp (expiration) against the current time using a timestamp converter if needed. Verify iss (issuer) and aud (audience) match your expected authorization server and API identifier. Use Copy to export decoded JSON for support tickets — after redacting sensitive claims. Use Clear when finished so tokens do not linger in browser memory longer than necessary on shared machines.

Standard Registered Claims

RFC 7519 defines registered claim names with recommended semantics. iss (issuer) identifies who minted the token — your Auth0 tenant URL, Cognito user pool, or corporate Keycloak realm. sub (subject) identifies the user or principal, often an opaque user ID. aud (audience) names the intended recipients; APIs should reject tokens whose audience does not include their identifier.

exp (expiration time) is a NumericDate — Unix seconds since epoch — after which the token must not be accepted. nbf (not before) rejects tokens used too early, useful for clock skew tolerance windows. iat (issued at) records mint time and helps detect stale tokens or replay in combination with revocation lists. jti (JWT ID) provides a unique token identifier for one-time use or revocation tracking.

Missing exp on access tokens is a security smell — always configure bounded lifetimes. Refresh tokens may live longer but should be stored server-side or in httpOnly cookies, not localStorage, when possible.

Public vs. Private Claims

Beyond registered claims, applications add private claims — custom fields like roles, permissions, tenant_id, or email. OAuth providers and identity platforms embed profile attributes in ID tokens (OpenID Connect) while access tokens carry scopes and resource permissions. Name collisions are avoided by using namespaced keys (https://example.com/roles) in federated scenarios.

When debugging authorization bugs, compare decoded claims against your policy engine's expectations. A user missing a admin: true claim might pass authentication but fail authorization middleware. Logging decoded claims in development (never production secrets) accelerates triage.

JWT Algorithms: HS256, RS256, and Beyond

HMAC algorithms (HS256, HS384, HS512) use a shared secret. The same secret signs and verifies. Simple for monoliths but difficult to rotate across many microservices without distributing secrets widely.

RSA and ECDSA algorithms (RS256, ES256) use public/private key pairs. The authorization server signs with a private key; APIs verify with published public keys from a JWKS (JSON Web Key Set) endpoint. This scales better for multi-service architectures and enables key rotation without redeploying every consumer.

The historic alg: none attack exploited servers that accepted unsigned tokens. Modern libraries reject none by default. Always validate algorithms against an allowlist on the server — decoding locally for inspection does not replace verification.

JWT in OAuth 2.0 and OpenID Connect

OAuth 2.0 defines authorization flows (authorization code with PKCE for SPAs, client credentials for machine-to-machine, device code for TVs). Access tokens may be opaque strings or JWTs depending on the authorization server. When JWT-shaped, they carry scopes in a scope claim or space-delimited string and expire quickly (minutes to hours).

OpenID Connect adds an ID token — always a JWT — proving authentication events. ID tokens include auth_time, nonce (bound to the authorization request for replay protection), and profile claims (email, name). Clients must validate ID token signatures against the provider's JWKS, check nonce, and verify aud matches the client ID.

Refresh tokens are often opaque and long-lived; decoding applies primarily to access and ID tokens. When an API returns 401, decode the access token: if exp passed, refresh the session; if claims look correct, investigate server-side clock skew or wrong signing keys after rotation.

Decoding vs. Verifying: Critical Distinction

Decoding parses Base64URL and displays JSON. Anyone can decode any JWT without secrets. Verification cryptographically validates the signature using the correct secret or public key and checks claims (exp, aud, iss). Only verification establishes trust. Browser-based decoder tools are for development debugging — production APIs must verify on every request before trusting claims.

Never paste production tokens with live privileges into untrusted online verifiers that send tokens to remote servers. ToolsFree.org keeps decoding local. Still treat decoded output as sensitive: emails, roles, and internal IDs may appear in payloads.

Common JWT Debugging Scenarios

Token expired immediately: Check exp and server clock sync (NTP). Confirm timezone confusion did not shorten lifetimes in configuration UI measured in minutes versus hours.

Invalid audience: API expects aud: api://my-service but token carries only client ID. Align resource server configuration with authorization server audience settings.

Algorithm mismatch after key rotation: APIs cache JWKS keys; stale cache rejects valid tokens. Flush cache or implement kid (key ID) header matching per RFC 7517.

Missing scopes: Access token decodes cleanly but lacks read:orders. Trace authorization grant and scope approval in the OAuth consent step.

Storage, XSS, and Token Exposure

SPAs storing access tokens in localStorage risk XSS exfiltration — any injected script reads tokens. HttpOnly cookies mitigate JavaScript access but require CSRF protections. Mobile apps use secure enclaves and keychains. Decoding helps incident response: if a token leaked, inspect exp to know when it becomes useless and whether jti supports revocation.

JWT vs. Session Cookies vs. PASETO

Classic server sessions store state server-side with a session ID cookie. JWTs push claims to the client, reducing database lookups but complicating revocation. PASETO is an alternative token format designed with safer defaults (no algorithm agility confusion). JWT remains dominant due to ecosystem support in Kong, AWS, Azure AD, Google, and every major framework middleware package.

Privacy and Safe Handling

Tokens are credentials. Decode locally on ToolsFree.org without network transmission. Redact tokens and payloads before screenshots. Rotate secrets if tokens appear in public issue trackers. Clear the decoder after use on shared workstations.