JWT: Signed JSON Claim Tokens

WHY IT EXISTS: JWT is a proposed Internet standard invented because distributed systems need to pass data between parties and prove the data has not been altered. Rather than requiring every receiver to query a central authority for every request, a token carries JSON assertions called claims along with optional proof of origin through signature or encryption. The goal is to let a recipient verify who created the data and decide whether to trust it without maintaining constant contact with the sender.

THE MENTAL MODEL: Imagine a postcard written in JSON. By default, anyone can read what is on it. If you want to prove you wrote it, you add a signature using either a private secret or a public/private key. If you also need to hide the contents from intermediaries, you optionally encrypt the postcard. The signature proves authenticity and integrity; encryption proves confidentiality. They are independent choices, so a token can be signed but unencrypted, encrypted but unsigned, both, or neither.

HOW IT WORKS: The payload of a JWT is JSON that asserts some number of claims. These claims are statements or pieces of data that the sender wants the receiver to accept. The token is signed using one of two approaches. The first approach uses a private secret, meaning the same key is shared between the party that creates the token and the party that verifies it. The second approach uses a public/private key, where the signer holds the private key and distributes the public key to anyone who needs to verify the signature. Encryption is optional, so the JSON payload may travel as readable text unless the creator explicitly encrypts it.

WHEN TO USE IT: Use a JWT when you need to transmit JSON claims between parties and the receiver must verify that the claims originated from a specific sender. It applies when you want the payload to carry signed assertions so the receiver can validate them independently. It also applies when the claim contents require optional encryption to prevent unauthorized reading during transit.

WHEN NOT TO USE IT: Do not use JWT if your JSON data does not need signature verification or encrypted payloads. Adding signing and key management creates unnecessary overhead for data that is already trusted or public. Remember that the payload is readable JSON unless encryption is explicitly applied, so do not store sensitive claims in a signed-only token and expect them to remain hidden.

ONE CANONICAL EXAMPLE: A server generates a JWT whose JSON payload asserts claims. The server signs the token with a private secret. A verifying party uses the same secret to check the signature and then reads the claims. Alternatively, the server could use a public/private key, signing with the private key so that any party with the corresponding public key can verify the origin of the claims without needing access to the server's secret.