Introduction to JSON Web Tokens

A complete guide to understanding JWTs — what they are, how they work, when to use them, and how encoding, decoding, validation, and verification differ.

What is JSON Web Token?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

JWTs can be signed using a secret with the HMAC algorithm, or a public/private key pair using RSA or ECDSA.

Although JWTs can be encrypted to also provide secrecy between parties, the most common use case focuses on signed tokens. Signed tokens can verify the integrity of the claims contained within them, while encrypted tokens hide those claims from other parties. When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

When should you use JSON Web Tokens?

Here are the most common scenarios where JSON Web Tokens are the right tool:

• Authorization — The most common use case. Once the user is logged in, each subsequent request includes the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single Sign-On (SSO) is a feature that widely uses JWT because of its small overhead and its ability to be used easily across different domains.
• Information Exchange — JWTs are a good way to securely transmit information between parties. Because JWTs can be signed — using public/private key pairs — you can verify the sender's identity. Additionally, since the signature is calculated using the header and the payload, you can verify that the content has not been tampered with.
• API Authentication — REST APIs often use JWTs as Bearer tokens in the Authorization header. The server can verify the token without maintaining server-side session state, enabling stateless, horizontally scalable architectures.
• Federated Identity / OpenID Connect — The OpenID Connect (OIDC) protocol builds on top of OAuth 2.0 and uses JWTs as ID Tokens to convey authenticated user information.

What is the JSON Web Token structure?

In its compact form, JSON Web Tokens consist of three parts separated by dots (.):

• Header
• Payload
• Signature

A JWT therefore looks like this:

Header

The header typically consists of two parts: the type of the token (which is JWT) and the signing algorithm being used, such as HMAC SHA256 or RSA.

This JSON is then Base64Url encoded to form the first part of the JWT.

Payload

The second part is the payload, which contains the claims. Claims are statements about an entity (typically the user) and additional metadata. There are three types of claims:

• Registered Registered claims — A set of predefined claims which are not mandatory but recommended, to provide a set of useful, interoperable claims. Examples include: iss (issuer), exp (expiration time), sub (subject), aud (audience), iat (issued at), and others defined in RFC 7519 §4.1. Note that claim names are intentionally only three characters long — JWT is meant to be compact.
• Public Public claims — Can be defined at will by those using JWTs. To avoid collisions, they should be registered in the IANA JSON Web Token Registry or be defined as a URI containing a collision-resistant namespace.
• Private Private claims — Custom claims created to share information between parties that agree on using them; they are neither registered nor public.

The payload is then Base64Url encoded to form the second part of the JWT.

Signature

To create the signature, you take the encoded header, the encoded payload, a secret, and the algorithm specified in the header, and sign that.

For example, using the HMAC SHA256 algorithm:

The signature verifies that the message was not altered in transit. When the token is signed with a private key, it also proves that the sender is who they claim to be.

Putting it all together, the output is three Base64Url strings separated by dots — compact enough to be passed in an HTTP header or URL parameter. Here is a real encoded JWT:

You can paste this token directly into our JWT Encoder & Decoder to inspect it, or experiment with the jwt.io Debugger.

How do JSON Web Tokens work?

In authentication, when the user successfully logs in using their credentials, a JSON Web Token is returned by the server. Since tokens are credentials, great care must be taken to prevent security issues. In general, you should not keep tokens longer than required.

Whenever the user wants to access a protected route or resource, the user agent should send the JWT — typically in the Authorization header using the Bearer schema:

This is a stateless authorization mechanism. The server's protected routes check for a valid JWT in the Authorization header. If the token is valid, the user is allowed to access protected resources. Because the token carries all the claims, the server may not need to query a database for certain operations.

A typical JWT authentication flow works as follows:

1. The client sends credentials (username + password) to the Authorization Server.
2. The Authorization Server validates the credentials and issues a JWT access token (and optionally a refresh token).
3. The client stores the token (e.g., in memory or a secure cookie) and attaches it to subsequent API requests via the Authorization: Bearer header.
4. The Resource Server (API) validates the JWT signature, checks claims (exp, aud, iss), and grants or denies access.
5. The token eventually expires (exp claim) and the client must re-authenticate or use a refresh token.

Why should we use JSON Web Tokens?

Let's compare JWTs against two older alternatives:

Because JSON is less verbose than XML, an encoded JWT is significantly smaller than a comparable SAML assertion. JSON parsers are native to virtually all programming languages, while XML requires a dedicated parser with no natural document-to-object mapping. These properties make JWT the default choice for modern web and mobile applications.

Difference Between Validating and Verifying a JWT

JWT validation and verification are often used interchangeably, but they address slightly different aspects of JWT security:

JWT Validation

Validation generally refers to checking the structure, format, and content of the JWT:

• Structure — Ensuring the token has the standard three parts (header.payload.signature) separated by dots.
• Format — Verifying that each part is correctly Base64Url encoded and that the payload decodes to valid JSON.
• Content / Claims — Checking that:
  • The token is not expired (exp claim).
  • The token is not used before its valid start time (nbf — Not Before).
  • The iat (issued at) timestamp is in the past.
  • Required claims are present.

JWT Verification

Verification confirms the authenticity and integrity of the token:

• Signature verification — The signature is re-computed from the header and payload using the known secret or public key, then compared against the signature in the token. If they don't match, the token may have been tampered with or forged. This step uses the algorithm declared in the header's alg field (e.g., HMAC, RSA, or ECDSA).
• Issuer verification — Checking that the iss claim matches the expected issuer.
• Audience verification — Ensuring the aud claim matches the expected audience (your application's identifier).

Difference Between Encoding and Decoding a JWT

Encoding a JWT

Encoding transforms a header and payload into the compact, URL-safe JWT string:

1. Serialize the header object to JSON, then Base64Url encode it.
2. Serialize the payload object to JSON, then Base64Url encode it.
3. Concatenate the two encoded strings with a dot: encodedHeader.encodedPayload.
4. Sign this string using the algorithm specified in the header (e.g., HMAC-SHA256 with a secret key, or RSA-SHA256 with a private key).
5. Base64Url encode the resulting binary signature.
6. Concatenate everything: encodedHeader.encodedPayload.encodedSignature.

Decoding a JWT

Decoding reverses the encoding process. It converts each Base64Url-encoded segment back into readable JSON. Decoding does not require any key — anyone who holds the token can decode the header and payload. This is why you must never store sensitive data in a JWT payload unless the token is also encrypted.

In many JWT libraries, "decoding" also implies verification: after decoding, the library re-computes the expected signature and compares it against the token's signature to confirm authenticity.