What is a JWT? A Simple Explanation for Developers

If you've worked with modern web applications, you've almost certainly encountered JSON Web Tokens, or JWTs (pronounced "jots"). They are the most common way to handle authentication and authorization for APIs and web services. A JWT is a compact, self-contained string that allows two parties to securely exchange information. But what is that long string of characters, and how does it work?

The Structure of a JWT

A JWT looks like a random jumble of characters, but it has a very specific structure. It consists of three parts, separated by dots (.):

[Header].[Payload].[Signature]

Let's break down each part.

1. The Header (The "What")

The first part is the Header. It's a simple JSON object that contains metadata about the token itself. It typically consists of two parts:

• alg (Algorithm): The signing algorithm being used to create the signature. This is usually something like HS256 (HMAC using SHA-256) or RS256 (RSA using SHA-256).
• typ (Type): The type of the token, which is always "JWT".

A typical header looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}

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

2. The Payload (The "Claims")

The second part is the Payload. This is another JSON object that contains the "claims," which are statements about an entity (typically the user) and additional data. The claims are the core information that the token is communicating. There are three types of claims:

• Registered Claims: These are a set of predefined claims that are not mandatory but recommended. They include iss (issuer), exp (expiration time), sub (subject), and aud (audience). The exp claim is particularly important, as it defines the time after which the JWT must not be accepted for processing.
• Public Claims: These can be defined at will by those using JWTs. But to avoid collisions, they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision-resistant namespace.
• Private Claims: These are the custom claims created to share information between parties that agree on using them. For example, you might include a user ID, a user role, or other permissions.

A sample payload might look like this:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

Like the header, this payload JSON is Base64Url encoded to form the second part of the JWT.

Important: The payload is encoded, not encrypted. This means anyone who intercepts the token can easily decode it and read its contents. Therefore, you should never put sensitive information in the JWT payload that you wouldn't want a third party to see.

3. The Signature (The "Proof")

The third part is the Signature. This is the most critical part for security. It's used to verify that the token has not been tampered with and, in the case of an asymmetric algorithm, to also verify the sender's identity.

To create the signature, you take the encoded header, the encoded payload, a secret key, and run them through the algorithm specified in the header (alg).

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

The signature ensures the integrity of the token. When a server receives a JWT, it performs the same signature calculation using the header, payload, and the secret key it has stored. If the signature it generates matches the signature on the token, it knows the token is authentic and the payload has not been changed since it was issued.

Hands-On with JWTs

The best way to understand the structure of a JWT is to see it for yourself. If you're working on an application that uses JWTs for authentication, you can copy one of those tokens (often found in your browser's local storage or in the Authorization header of network requests) and paste it into a debugger tool.

Our JWT Debugger provides a simple, secure way to do this. It decodes the Base64Url parts of the token and displays the header and payload in a readable format, all within your browser so your token is never transmitted over the network. This allows you to quickly inspect the claims and verify the contents of your tokens while debugging.