JWT Parser

A JSON Web Token (JWT, pronounced "jot") is a compact, URL-safe token format defined in RFC 7519. It lets two parties exchange claims — small pieces of JSON data — in a way that can be cryptographically verified. Because the token is self-contained, the recipient can validate it without calling back to the issuer, which makes JWTs popular in stateless authentication architectures.

JWTs are widely adopted across the web. OAuth 2.0 access tokens, OpenID Connect ID tokens, and many API gateway sessions are all carried as JWTs. Understanding their structure is essential for debugging login flows, inspecting API responses, and auditing token-based security.

A JWT consists of three Base64url-encoded parts separated by dots: header.payload.signature.

Header — A JSON object that describes the token type (typ, usually "JWT") and the signing algorithm (alg, such as HS256, RS256, or ES256). Some headers also include a key ID (kid) used to look up the correct verification key.

Payload — The claims set. This is the actual data you care about: user identity, permissions, token lifetime, and any custom fields your application needs. The payload is encoded, not encrypted, so anyone who has the token can read it.

Signature — Created by signing the encoded header and payload with a secret (HMAC) or a private key (RSA/ECDSA). The signature lets the recipient verify the token has not been tampered with and, with asymmetric algorithms, confirm who issued it.

The JWT specification defines several registered claims that provide interoperable metadata about the token:

• iss (Issuer) — Identifies the principal that issued the token, such as your auth server's URL.
• sub (Subject) — The entity the token refers to, typically a user ID.
• aud (Audience) — The intended recipient of the token, often an API identifier.
• exp (Expiration Time) — A Unix timestamp after which the token must be rejected.
• iat (Issued At) — The Unix timestamp when the token was created.
• nbf (Not Before) — The token should not be accepted before this Unix timestamp.

Beyond these, applications regularly add custom claims such as roles, scope, email, or tenant_id. Keep custom claims concise — every byte increases the token size, and tokens travel with every HTTP request.

OAuth 2.0 & OpenID Connect — Access tokens, refresh tokens, and ID tokens are frequently issued as JWTs. The ID token in particular is always a JWT, carrying identity claims from the authorization server to the client application.

Single Sign-On (SSO) — JWTs enable SSO by carrying authentication state across services. Once a user authenticates with an identity provider, the resulting JWT can grant access to multiple downstream applications without additional login prompts.

API Authentication — Stateless APIs use JWTs in the Authorization: Bearer header. Because the token is self-contained, the API can verify the caller's identity and permissions without a database lookup on every request.

Microservice Communication — In service-to-service calls, a propagated JWT lets downstream services verify the original caller's identity and enforce fine-grained authorization at each hop.

Never store secrets in the payload. The payload is only Base64url-encoded, not encrypted. Treat it as public data. Anyone who intercepts the token can decode and read every claim. If you need confidentiality, use JWE (JSON Web Encryption) instead of a plain JWS.

Always verify signatures server-side. A common vulnerability is accepting tokens without verifying the signature, or trusting the alg field in the header without restriction. Pin the allowed algorithms on the server and reject "alg": "none".

Set short expiration times. The exp claim should be as short as practical — minutes for access tokens, not days. Pair short-lived JWTs with refresh tokens to balance security and user experience.

Rotate signing keys. If a signing key is compromised, every token ever issued with it can be forged. Use key rotation with the kid header and a JWKS endpoint so consumers always fetch the latest keys.

Validate all registered claims. Always check iss, aud, exp, and nbf on the server side. Skipping these checks opens the door to token replay and cross-tenant attacks.

JWS (JSON Web Signature) is what most people mean when they say "JWT." The payload is readable by anyone, but the signature guarantees integrity — if someone changes a single character, verification fails. JWS is the right choice when you need authentication and integrity but not confidentiality.

JWE (JSON Web Encryption) encrypts the payload so only the intended recipient (who holds the decryption key) can read the claims. JWE tokens are larger and more complex to implement, but necessary when the token carries sensitive data such as personal information or financial details.

In practice, many systems combine both: a JWS for the access token (where the API only needs to verify identity) and a JWE for tokens that carry confidential user attributes between services.

Token expired — Check the exp claim. If it is in the past relative to the server's clock, the token is rejected. Clock skew between servers is a frequent cause; most libraries accept a small leeway (e.g., 30 seconds).

Invalid signature — Confirm the signing key matches the kid in the header. If your JWKS endpoint was recently rotated, cached keys may be stale. Also verify the alg matches what the server expects.

Audience mismatch — The aud claim must match the API's expected identifier. This commonly fails when using tokens across environments (e.g., a staging token hitting a production API).

Malformed token — If the token doesn't split into three dot-separated parts, it isn't a valid JWS. Paste it into the parser above to see exactly where the structure breaks down.

JWT payloads are Base64url-encoded JSON. Use these companion tools to work with the underlying data:

• Base64 Encoder/Decoder — Encode or decode raw Base64 and Base64url strings.
• JSON Formatter — Pretty-print and validate the JSON from a decoded header or payload.
• Hash Generator — Compute HMAC-SHA256 and other hashes used in JWT signatures.