For the complete documentation index, see llms.txt. This page is also available as Markdown.

Understanding JWT and JWS

Overview

ProofPacks are usually handed around as a JWT or a JWS — two closely related, industry-standard token formats. This page explains what each one is, how they differ, and why ProofPack uses them, without assuming any prior cryptography background.

What Is a JWS?

A JWS (JSON Web Signature) is a standard way of taking a piece of JSON data and cryptographically signing it, so that anyone holding it can verify it hasn't been tampered with and came from whoever holds the signing key.

A JWS has three parts, joined by dots, commonly written as:

header.payload.signature
  • Header: describes the signing algorithm used (e.g. ES256).

  • Payload: the actual data being signed — in ProofPack's case, this is the Merkle tree and its root hash.

  • Signature: a cryptographic signature over the header and payload, produced with a private key.

Anyone with the corresponding public key (for example, an Ethereum wallet's address) can verify the signature without needing to trust whoever is presenting the token — the maths either checks out or it doesn't.

Why this matters for ProofPack A JWS envelope is what turns a Merkle tree from "some JSON someone sent you" into "cryptographically proven to have been signed by this specific wallet, and unmodified since." See Understanding Merkle Trees and Proofs for what's actually inside that payload.

What Is a JWT?

A JWT (JSON Web Token) is a widely-used standard for compact, self-contained tokens, most often seen carrying login sessions or API claims. Structurally, a JWT is a specific case of a signed token with a standard set of payload conventions (things like an issuer, an expiry, and a subject).

In practice, a ProofPack presented as a JWT is a JWS whose payload follows those JWT conventions — which is why you'll often see "JWS or JWT" mentioned interchangeably in ProofPack documentation. The distinction that actually matters when integrating:

  • A JWS is the general signed-envelope mechanism.

  • A JWT is a JWS (or similar) with a standardised payload shape, which makes it easy to drop into existing tooling that already expects JWTs — such as an Authorization: Bearer <token> header.

Why ProofPack Uses These Formats

Rather than invent a bespoke signed-token format, ProofPack builds on JWS/JWT because:

  • Existing tooling works. Any library, gateway, or middleware that already handles Bearer tokens or JWS verification can handle a ProofPack with little to no custom code.

  • Offline verification. Both formats can be verified using just the payload and a public key — no call back to Zipwire is required.

  • Familiarity. Most backend developers have already integrated JWT-based auth at least once, so the mental model transfers directly.

Where to Go Next

Proof VerificationGetting a ProofPack JWT with a Nationality ClaimPath 2: JWS with claims (JavaScript)Understanding Merkle Trees and Proofs

Last updated