Before looking inside a JWT, it helps to understand the gap it fills within the broader OAuth 2.0 picture.

Earlier tutorials in this series explained how OAuth 2.0 hands out access tokens and refresh tokens after a user approves a request. Those tutorials deliberately left one detail open: what does an access token actually look like on the inside? OAuth 2.0 itself does not require any particular token format — a token can be a completely random, meaningless string that only the Authorization Server understands, known as an “opaque token.” A JWT is a popular, standardized alternative format that many Authorization Servers choose instead, because it can carry readable information directly inside itself.

The key idea to hold onto throughout this tutorial is that a JWT is not encrypted or secret by default. Its contents can be read by anyone who gets hold of it, in the same way anyone can read an unsealed letter once it is opened. What a JWT guarantees instead is integrity: proof that whatever is written inside has not been quietly changed since the moment it was created and signed.

Every JWT, without exception, is built from exactly three sections, joined together with a period character.

If you were to look at a JWT written out as plain text, it would appear as three chunks of jumbled-looking characters, separated by two dots, in the pattern “first-part.second-part.third-part.” Each of these three chunks has a specific, well-defined job.

flowchart LR
    subgraph JWT["A Single JWT String"]
      H["Header\n(algorithm + token type)"] --> P["Payload\n(claims about the user or grant)"]
      P --> S["Signature\n(proves nothing was changed)"]
    end
        

The jumbled-looking text in each section is not encrypted — it is simply encoded in a way that is safe to place inside a web address or an HTTP header.

Both the header and the payload start out as ordinary, human-readable structured data — essentially a small set of labeled facts, similar to a short form with field names and values. Before being placed into the token, each of these two sections is run through a standard, entirely reversible encoding process called Base64URL encoding. This encoding does not hide or protect the content in any meaningful way; it exists purely to turn the data into a compact set of letters, numbers, and a couple of safe symbols that will not break when placed inside a URL or a network header.

Because of this, a golden rule follows naturally: never place a genuinely sensitive secret, such as a raw password, directly inside a JWT’s payload, since anyone who obtains the token can read it in seconds. JWTs are meant to carry claims that are safe to be seen by their intended recipients, protected against tampering rather than protected against reading.

The header is deliberately small — usually just a couple of fields describing the token itself.

The “kid” field deserves a moment of attention, because it solves a very practical problem. Authorization Servers periodically rotate their signing keys for security hygiene, much like periodically changing the combination on a safe. When multiple keys might be valid at once during a rotation period, the “kid” field tells the token’s recipient exactly which key to fetch and use when checking the signature, rather than needing to guess or try every available key.

The payload is where the actual useful information lives, organized as a set of individual facts called “claims.”

A claim is simply one labeled fact inside the payload, similar to a single filled-in field on a form, such as “issued by” or “expires at.” Some claim names are standardized and mean the same thing across virtually every system that uses JWTs, which makes tokens from different companies still somewhat predictable to read and validate.

This chapter explains the actual mechanics behind the tamper-evident seal, without requiring any background in cryptography.

When the Authorization Server creates a JWT, it takes the already-encoded header and payload, combines them, and runs that combination through a mathematical signing process using a secret or private key that only the Authorization Server possesses. The output of that process is the third and final section of the token: the signature. Crucially, this signature is mathematically tied to the exact contents of the header and payload used to create it.

sequenceDiagram
    participant A as Authorization Server
    participant C as Client / Resource Server

    A->>A: 1. Build header and payload
    A->>A: 2. Sign header+payload using a secret/private key
    A->>C: 3. Send complete JWT (header.payload.signature)
    C->>C: 4. Recompute the signature using the known public/shared key
    C->>C: 5. Compare recomputed signature to the one in the token
    Note over C: Match = trustworthy and unaltered.\nMismatch = reject the token.
        

When a Resource Server later receives this JWT, it performs the same signing calculation itself, using the matching key it already knows about or trusts, and compares its own freshly computed result against the signature that came attached to the token. If even a single character in the header or payload had been altered after the token was originally signed, the recomputed signature would come out completely different, and the mismatch would immediately reveal the tampering.

Not every JWT is signed the same way. Understanding the two main families clarifies who can create tokens and who can only verify them.

Since OAuth 2.0 does not require any particular token format, it is worth comparing the two dominant styles directly.

Neither style is universally “better” — they represent a genuine trade-off between the speed and independence of local verification and the tighter, centrally controlled revocation that comes from always checking back with the Authorization Server. Many large-scale systems address this trade-off by combining both approaches: JWTs with short lifespans for everyday API calls, alongside a separate, centrally checked mechanism for anything that needs instant revocation.

Yes, assuming they have the token itself. The header and payload are only encoded, not encrypted, so anyone holding the token can decode and read both sections in seconds using a basic, freely available tool.

Technically the text can be edited by anyone, but doing so breaks the mathematical relationship between the content and the signature, so any properly implemented verifier will immediately detect the mismatch and reject the altered token.

No. OAuth 2.0 is a framework describing how permission is granted and tokens are issued. A JWT is simply one popular format those tokens can be written in — OAuth 2.0 works equally well with opaque, non-JWT tokens.

Because a JWT is verified locally using its signature, instant revocation is not built in by default. Systems that need this typically keep token lifespans very short, or maintain a separate, centrally checked list of revoked token identifiers alongside the JWT itself.

Length mostly reflects how many claims are packed into the payload and which signing algorithm was used, since some algorithms produce naturally longer signature sections than others.

A JWT is best understood as a sealed, readable letter rather than a locked box. Its three parts — header, payload, and signature — work together to carry useful, structured information while guaranteeing that nothing has been quietly altered since it was created. The header describes how the token was signed, the payload carries the actual claims, and the signature acts as the tamper-evident seal tying the two together. Because a JWT can always be read by anyone holding it, its real security value lies entirely in integrity, not secrecy, which shapes every best practice covered in this tutorial, from choosing the right signing algorithm to keeping sensitive data out of the payload entirely.