# JSON Web Token \(JWT\)

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

- Type: artifact
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/json-web-token/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A practical 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/json-web-token/#visualization-json-web-token>)

## Sources

1. [JSON Web Token \(JWT\) \(RFC 7519\)](<https://www.rfc-editor.org/rfc/rfc7519>) — RFC Editor · Internet Standard
2. [JSON Web Token Best Current Practices \(RFC 8725\)](<https://www.rfc-editor.org/rfc/rfc8725>) — RFC Editor · Best Current Practice

## Related topics

- [OAuth 2.0](<https://wiki.soroush.uk/topic/oauth-2-0/>)
- [OpenID Connect \(OIDC\)](<https://wiki.soroush.uk/topic/openid-connect/>)
- [Session](<https://wiki.soroush.uk/topic/session/>)
