The Complete JWT Guide

JWT (JSON Web Token) is a compact, URL-safe token format defined by RFC 7519. It lets two parties securely transmit information as a JSON object.

There are three core design goals:

• Self-contained: The token itself carries all the context. The server can authenticate without querying a database, making horizontal scaling straightforward.
• Tamper-proof: A digital signature (HMAC or RSA / ECDSA) guarantees that the Header and Payload have not been altered in transit.
• Easy to use: A three-part structure plus Base64URL encoding makes JWT easy to carry in HTTP headers, URL parameters, or cookies — with excellent cross-language and cross-platform support.

A JWT has three parts, each separated by a dot (.):

• Header: declares the signing algorithm (alg), token type (typ), and optional kid (key ID).
• Payload: carries business claims such as user ID, roles, permissions, and lifetime.
• Signature: the result of signing the first two parts — used to verify integrity and origin.

Typical appearance (three segments separated by dots, shown one per line below):

Each part is Base64URL-encoded and readable by anyone — a critical fact we return to in section #07.

With our JWT tool, you can paste any token and click "Parse / Verify" to instantly inspect the Header and Payload — a very productive way to debug APIs.

The Header is the token's meta-information area. The most common fields:

• alg: signing algorithm — typical values include HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256. The unsafe none value should always be rejected in production.
• typ: token type — usually JWT — used to distinguish JWT from other formats (JWS / JWE / JWK / JWKS).
• kid: key ID — used when the server holds multiple keys (e.g. during rotation) to indicate which key was used for signing.

The Payload is the "body" of the JWT. For interoperability, RFC 7519 defines a set of registered claims:

• iss (issuer): identifies who issued the token — useful in multi-tenant scenarios.
• sub (subject): identifies the principal — usually a user ID.
• aud (audience): the intended recipient(s). The server should verify it matches itself.
• exp (expiration): Unix timestamp — the token expires at this time. Recommended lifetime is 15 minutes to 2 hours — shorter is safer.
• nbf (not before): Unix timestamp — the token is invalid before this time.
• iat (issued at): timestamp of when the token was issued.
• jti (JWT ID): a unique identifier for the token — useful for implementing one-time tokens or blacklists.

Practical advice: keep the number of Payload fields to fewer than 10. Too many fields bloat the token beyond several kilobytes and hurt HTTP header performance. Also, never store passwords, ID numbers, phone numbers, or bank card numbers — Base64URL is not encryption.

In our online tool, fill the Payload as JSON and click "Sign" to obtain a complete token — you can see in real time how different claims affect the output.

JWT supports three main families of signing algorithms, each with its own key-management model and security strength. Picking the right one is the most important architectural decision.

• HS series (HS256 / HS384 / HS512): HMAC-based symmetric signatures — signing and verification use the same secret key. The simplest to implement, fastest to compute, and the best-supported across languages. Drawback: anyone holding the key can issue valid tokens, so the secret must be strictly controlled and never distributed to many independent servers.
• RS series (RS256 / RS384 / RS512): RSA-based asymmetric signatures — sign with the private key, verify with the public key. Public keys can be safely distributed to many servers; a leaked public key cannot be used to forge tokens. Drawback: signing and verification cost more than HMAC, and tokens are larger (a 2048-bit RSA signature adds ~342 characters).
• ES series (ES256 / ES384 / ES512): ECDSA (elliptic-curve) asymmetric signatures — similar to RS but with shorter signatures (ES256 ≈ 86 characters) and lower computational overhead. Ideal for mobile, IoT, and edge nodes with constrained resources.

Recommendation:

• Monolithic / internal systems → HS256 (simple and fast)
• Multi-server, OpenID Connect, OAuth2 authorization server → RS256 (the industry default — public keys can be openly distributed)
• Mobile / IoT / edge nodes / bandwidth-sensitive → ES256 (smaller and faster)

With our JWT tool, you can switch between HS256 / HS384 / HS512 / RS256 / RS384 / RS512 / ES256 / ES384 / ES512 in the same UI to compare signature lengths and formats.

JWT appears in almost every system that combines "identity + horizontal scaling". Here are 7 typical scenarios:

• API authentication: the front-end receives a JWT after login, then includes it in subsequent requests via Authorization: Bearer {token}. The server only verifies the signature and lifetime — no session lookups needed.
• Inter-service authentication (microservices): service A issues a short-lived token (e.g. 1 minute) using HS256 or RS256 to call service B. B only verifies the signature and lifetime — stateless and high-performance.
• Single Sign-On (SSO): once logged in, a JWT can be consumed by multiple sub-domains or independent applications, as long as all parties trust the issuer's public key / secret.
• OpenID Connect (OIDC) / OAuth2: modern identity providers (Auth0, Okta, Azure AD, Keycloak...) default to JWT as the carrier for ID Tokens and Access Tokens.
• One-time URLs / download links: encode a claim such as "user may download file X for 10 minutes" into a JWT — the server can simply verify the signature without maintaining any temporary state.
• Mobile and SPA local sessions: React, Vue, Flutter, Swift, and others have first-class JWT parsing support, so clients can quickly display user info.
• Webhook callback verification: some platforms attach a JWT containing request summary and metadata to callback headers, allowing the receiver to verify source and integrity.

For all these scenarios, our online JWT tool lets you locally reproduce the token structure so you can quickly decide whether the issue is "missing token on the client", "server-side verification logic", or "key / algorithm mismatch".

The three approaches are not mutually exclusive — real projects often combine them. Here are the core differences:

• Traditional Session Cookie: the server keeps the session state in a store (Redis / DB); the client only holds an unguessable session ID. Pros: revocation is trivial (just delete from the store). Cons: horizontal scaling requires a shared session store and creates performance bottlenecks; poor cross-domain experience.
• JWT (self-contained): the server keeps no session state — it only verifies the signature and claims. Pros: stateless; easy horizontal scaling; great cross-language and cross-domain experience. Cons: revocation is harder; payload grows with fields; payload is not encrypted so sensitive data must not be stored there.
• Opaque Token: the client only holds a random string; the server must look up a data store to obtain user information (e.g. OAuth2 "reference tokens"). Pros: immediate revocation; no user data exposed to the client. Cons: every authentication requires a store lookup; depends on highly-available storage.

Recommendation:

• Monolithic back-end, small user base → Session Cookie
• Multi-service, microservices, cross-domain SSO, mobile → JWT
• Finance-grade, require immediate revocation, never expose any user data → Opaque Token + server-side lookup

The hybrid best-practice: short-lived Access Token (JWT) + long-lived Refresh Token (random string). Access Token powers authentication and automatically expires; Refresh Token is used to obtain new Access Tokens and can be blacklisted on the server. This is the dominant pattern in OAuth2 and modern applications.

To verify that your generated JWT matches what the server expects, paste the same secret / private key and Payload in our JWT tool and compare the signatures.

The JWT formula looks simple, but tiny differences between implementations lead to signature failure all the time. Here are six practical troubleshooting tips:

• Agree on character encoding and JSON serialization: the signature is computed over base64url(header).base64url(payload). The JSON serialization (key order, whitespace, line breaks) must be identical on both sides. Use the same library's default serialization — never manually build strings.
• Agree on key material format: for HS256, the key is a byte array (usually the UTF-8 bytes of a string); some servers expect the key to be Base64-decoded first. For RS256 / ES256, a PEM-formatted key is expected. Type mismatches are the #1 cause of failure.
• Check that the server accepts the algorithm you're using: some servers only allow a specific algorithm (e.g. RS256 only) and reject tokens declaring a different alg. Also, always reject alg=none on the server.
• Synchronize clocks and time units: exp / nbf / iat are Unix timestamps in seconds (not milliseconds). A clock drift of 5+ minutes can cause valid tokens to be reported as expired. Always enable NTP on servers.
• Verify kid and key material match: in multi-key scenarios, if the kid in the Header does not correspond to the key used for signing, verification always fails. Confirm that the JWKS (JSON Web Key Set) endpoint publishes the matching key.
• Watch for PEM whitespace issues: RSA / EC private and public keys are sensitive to line breaks. Do not drop the header / footer markers (-----BEGIN PUBLIC KEY-----) and do not introduce extra whitespace.

By re-signing the same input + same algorithm in our local tool and comparing the output against the server expectation, you can quickly tell whether the issue is "wrong parameters" or "a different library".

Issuing a valid JWT is only the beginning — real risks live in transmission and storage. Follow these production-grade recommendations:

• Always transmit over HTTPS: prevents tokens from being intercepted on the network. For cookie-based tokens, enable the Secure, HttpOnly, and SameSite=Strict (or Lax) flags.
• Keep token lifetimes short: Access Tokens should live 15 minutes or less; pair them with Refresh Tokens for renewal. Refresh Tokens can be valid for days to weeks and should be tracked on the server for immediate revocation.
• Never store sensitive data in the Payload: Base64URL is encoding, not encryption — anyone can decode it. If you must carry sensitive data, use JWE (JSON Web Encryption) for content-level encryption, or store only a non-sensitive reference ID in the Payload.
• Use long keys and strong algorithms: at least 32 bytes (256 bits) for HS256 — preferably 64+ bytes; at least 2048-bit RSA for RS256; the P-256 curve for ES256.
• Enforce a strict algorithm whitelist server-side: never accept alg=none; for RS256 deployments, enforce an algorithm + key-type match to prevent "algorithm confusion" attacks.
• Verify registered claims: at minimum, verify exp (expiration), iss (issuer), and aud (audience). Verify nbf when applicable.
• Do not store tokens in long-lived localStorage: localStorage is vulnerable to XSS — once a script is injected, the attacker can read every token. Prefer HttpOnly cookies; if you must store tokens client-side, shorten their lifetime and clear them on logout.
• Key rotation with kid: assign each key a kid and carry it in the Header. Publish public keys via a JWKS endpoint. During rotation, add a new key while the old key still verifies tokens during the transition period.

Choosing an online JWT tool that runs entirely locally, without logging or uploading, gives you convenience without surrendering control of your keys.