artifactEngineering & architecture

JSON Web Token (JWT)

A compact claims format that can be digitally signed or authenticated and optionally encrypted for transfer between parties.

Download Markdown (.md)

01What it means

A JSON Web Token (JWT) is a compact representation of claims encoded in JSON and carried in a sequence of URL-safe parts. JWTs are commonly signed as JSON Web Signatures and can be encrypted as JSON Web Encryption. A JWT is a token format, not an authentication method, session strategy, or guarantee of trust.[1][2]

Compact claims representation A signed JWT carries three URL-safe parts
  1. HeaderToken type and allowed algorithm
  2. PayloadClaims such as issuer, audience, expiry
  3. SignatureIntegrity and issuer-key verification

The format carries claims; trust comes only after strict algorithm, signature, issuer, audience, time, and protocol validation.

02Why it matters

JWTs allow a recipient to validate issuer-supplied claims without a lookup when keys and policy are known. This supports federation and distributed APIs, but stale claims, bearer-token theft, and incorrect validation can broaden impact.

03When to use it

Use JWTs when a standardized self-contained claims token is required by a protocol such as OIDC or by a distributed trust design. Prefer opaque identifiers when immediate revocation, minimal disclosure, or server-controlled session state matters more than offline validation.

04How it works

  1. Define the issuer, recipients, allowed algorithms, required claims, lifetime, and key-management policy.
  2. Create claims and a protected header, then sign or encrypt using the selected JOSE mechanism.
  3. Transmit the token only through a protected channel to its intended recipient.
  4. Parse defensively and verify the algorithm, signature, issuer, audience, time, and protocol-specific claims.
  5. Apply authorization separately and rotate keys, expire tokens, and handle revocation needs.

05A practical example

Example

An identity provider issues an OIDC ID Token as a signed JWT for one web client. The client verifies the provider's key and checks issuer, audience, nonce, and expiry before creating its own session.

06Where it breaks

Signed JWT contents are readable unless encrypted, and signature validity does not make claims current or appropriate. Self-contained tokens complicate immediate revocation, grow request size, and amplify mistakes in algorithms, audiences, keys, and storage.

Common mistakes

  • Decoding a JWT and trusting claims without verifying its signature and required claims.
  • Accepting whatever algorithm the token header requests.
  • Putting secrets or excessive personal data in an unencrypted token.
  • Using long-lived JWTs to avoid session or revocation design.

07Sources

  1. JSON Web Token (JWT) (RFC 7519)RFC Editor · Internet StandardJSON Web Token (JWT) (RFC 7519)
  2. JSON Web Token Best Current Practices (RFC 8725)RFC Editor · Best Current PracticeJSON Web Token Best Current Practices (RFC 8725)
View saved topics

Start typing to search titles, definitions, categories, and frameworks.