RFC 7519 · JSON Web Signature

Introduction to JWT

JSON Web Token (JWT) is an open standard (RFC 7519) for representing claims as a compact, URL-safe string. It is widely used with OAuth 2.0 and OpenID Connect, but the format itself is generic: any party that holds the right verification material can check the signature and reason about the claims inside—within the limits of how keys and clocks are managed.

This page explains how a JWT is built, how to read each part, and what guarantees you should—and should not—expect from the token alone.

01

Compact serialization and encoding

In the usual form (JSON Web Signature, JWS), a JWT is three segments separated by dots: header, payload, and signature. The first two segments are JSON objects encoded with Base64URL (not standard Base64): padding is often omitted and URL-safe characters are used so the token can travel in headers and query strings.

Base64URL encoding is not encryption. The header and payload are readable by anyone who has the string. The signature proves that the first two segments were produced by a party that controls the signing key; it does not hide their contents.

02

Structure of a JWT

Each segment has a distinct role in the compact JWS form:

Header

Typically includes typ (type, often "JWT") and alg (signing algorithm). It may also carry kid (key id) to pick the right public key from a JWKS, or other metadata required by your stack.

Payload

A JSON object containing the claims: statements about a subject, validity window, audience, and application-specific fields. Nested objects are allowed when your issuer defines them.

Signature

A cryptographic value over the bytes of "header.payload" (the two encoded segments and the dot between them), using the algorithm from the header and either a shared secret (HMAC) or an asymmetric private key (RSA, ECDSA, EdDSA).

03

Claims: what is inside the payload

Claims are name/value pairs. Their meaning depends on context, but RFC 7519 defines a set of registered claim names so libraries and APIs can interpret them consistently.

Registered claims

Common examples include iss (issuer), sub (subject), aud (audience), exp (expiration time), nbf (not before), iat (issued at), and jti (JWT ID). exp and nbf are Unix timestamps; validating them correctly requires a trusted clock on the verifier.

Public claims

Names can be registered in the IANA "JSON Web Token Claims" registry when you want interoperability across many implementations. They are still just conventions until producers and consumers agree on semantics.

Private claims

Names agreed between the issuer and the consumer of the token (for example internal roles or tenant identifiers). Avoid colliding with registered names unless you fully control both sides.

04

Algorithms at a glance

The alg value in the header selects how the signature is computed. Choosing the wrong model affects who can verify the token and how secrets are shared.

  • HMAC (HS*): one shared secret signs and verifies. Simple for a single service, but every verifier must possess the secret.
  • RSA or ECDSA/EdDSA: the issuer signs with a private key; verifiers use the public key (often distributed via JWKS). This fits microservices and public clients that must not hold signing secrets.
  • The "none" algorithm must not be accepted in production: it would allow unsigned tokens if misconfigured. Reject unknown or disabled algorithms explicitly.
05

Security: trust, privacy, and validation

A valid signature shows that the token was issued by someone who controls the signing key and that header and payload were not altered. It does not, by itself, encrypt anything.

Never put passwords, API keys, or other long-lived secrets in the payload. For confidential payloads in addition to signing, use TLS in transit and consider encrypted JWT (JWE)—a different format and workflow.

Servers should validate signature with the expected key or JWKS, check exp (and usually nbf), enforce aud and iss when your architecture relies on them, and use short lifetimes plus refresh flows where appropriate.

06

Common uses

JWTs are often used to:

  • Represent authenticated identity and authorization decisions (bearer access tokens, ID tokens in OpenID Connect)
  • Propagate identity or delegated authority between services in a distributed system
  • Model session or "logged-in" state in clients when paired with secure storage and refresh strategies
  • Carry OAuth 2.0 scopes or custom claims for API gateways and resource servers
07

Practical limits

Useful constraints to keep in mind when designing with JWTs:

  • Size: tokens are often sent in HTTP headers; large payloads increase latency and may hit proxy limits.
  • Revocation: a purely stateless JWT cannot be revoked instantly without extra infrastructure (deny lists, introspection, or very short lifetimes).
  • Clock skew: validation of exp and nbf depends on reasonably synchronized clocks between issuers and verifiers.