What is a JSON Web Token (JWT)?

Introduction

JSON Web Tokens, universally abbreviated as JWTs and pronounced “jots,” are one of the most widely used token formats in modern web development. Defined by RFC 7519, a JWT is a compact, URL-safe means of representing claims between two parties. In practical terms, a JWT lets a server create a token that says “this user is authenticated and has these permissions,” and the client can carry that token with subsequent requests.

JWTs are used everywhere: authentication systems, API authorization, single sign-on (SSO), microservices communication, and even email verification links. If you have built or consumed a REST API in the last decade, chances are you have encountered JWTs.

The Three-Part Structure

Every JWT consists of exactly three parts separated by dots. You can think of it as a sandwich: the header and signature are the bread, and the payload is the filling. Here is the anatomy of a JWT:

┌─────────────────────────┐
│         HEADER          │  Algorithm & token type
│  {"alg":"HS256","typ":"JWT"}  │
└─────────────────────────┘
              .
┌─────────────────────────┐
│         PAYLOAD         │  Claims (data)
│  {"sub":"1234567890",   │
│   "name":"John Doe",   │
│   "iat":1516239022}     │
└─────────────────────────┘
              .
┌─────────────────────────┐
│       SIGNATURE         │  Integrity verification
│  HMACSHA256(            │
│    base64url(header) +  │
│    "." +                │
│    base64url(payload),  │
│    secret               │
│  )                      │
└─────────────────────────┘

1. Header

The header is a JSON object that typically contains two properties: alg (the signing algorithm) and typ (the token type, almost always “JWT”). For example:

{
  "alg": "HS256",
  "typ": "JWT"
}

The header tells the receiver which algorithm was used to create the signature, so it knows how to verify the token. Common algorithms include HS256 (HMAC with SHA-256), RS256 (RSA with SHA-256), and ES256 (ECDSA with P-256 and SHA-256). You can learn more about these in our guide to JWT signing algorithms.

2. Payload

The payload is where the actual data lives. It contains claims -- statements about the user or entity and additional metadata. There are three categories of claims:

• Registered claims: Standardized by the JWT specification. These are not mandatory but are recommended for interoperability. They include iss, sub, aud, exp, nbf, iat, and jti.
• Public claims: Defined by developers and registered in the IANA JSON Web Token Claims registry to avoid collisions.
• Private claims: Custom claims agreed upon by the parties using the JWT. These are the most common in practice.

3. Signature

The signature is created by taking the encoded header, the encoded payload, a secret (or private key), and the algorithm specified in the header, and signing them. For HMAC-based algorithms:

HMACSHA256(
  base64urlEncode(header) + "." + base64urlEncode(payload),
  secret
)

The signature serves two purposes: it verifies the token was not tampered with (integrity) and, in the case of asymmetric algorithms, it also verifies who sent the token (authentication of the issuer).

Base64url Encoding

A critical detail that trips up many developers: JWTs use base64url encoding, not standard base64. The difference is subtle but important. Base64url replaces + with - and / with _, and it omits padding characters (=). This makes the resulting string safe for use in URLs, HTTP headers, and HTML attributes without additional encoding.

This is why every JWT starts with eyJ -- it is the base64url encoding of {"a, the beginning of the JSON header object. If you see a string starting with eyJ, it is almost certainly a JWT.

Standard Registered Claims

The JWT specification defines seven registered claims. While all are optional, using them correctly is essential for building secure and interoperable systems.

Note that the time-based claims (exp, nbf, iat) use Unix timestamps -- the number of seconds since January 1, 1970 (UTC). If you need to convert between Unix timestamps and human-readable dates, our Epoch Converter makes this straightforward.

Signed vs. Encrypted Tokens

An important distinction that many developers overlook: a standard JWT (technically a JWS, or JSON Web Signature) is signed but not encrypted. Anyone with access to the token can decode the header and payload -- the signature only ensures the data has not been tampered with.

If you need to hide the payload contents, you need a JWE (JSON Web Encryption) token. JWE tokens encrypt the payload so that only parties with the correct key can read the claims. In practice, JWE is less common because most JWT use cases only require integrity verification, not confidentiality.

The takeaway: never put sensitive information like passwords, credit card numbers, or private keys in a standard JWT payload. The claims are encoded, not encrypted -- anyone who intercepts the token can read them.

When to Use JWTs

JWTs shine in several scenarios:

• Stateless authentication: The server does not need to store session data. The token itself carries all necessary information. This is particularly valuable in distributed systems and microservices.
• Cross-domain authentication: JWTs work well across different domains and services because they are self-contained. A token issued by auth.example.com can be verified by api.example.com.
• API authorization: JWTs can carry scopes and permissions, allowing fine-grained access control without database lookups on every request.
• Information exchange: When you need to securely transmit a small amount of structured data between parties and ensure it has not been modified.
• Network-scoped access control: Some systems embed allowed IP ranges or CIDR blocks directly into JWT claims to restrict token usage to specific network segments. For example, a claim like "allowed_networks": ["10.0.0.0/24"] can enforce that the token is only valid from a particular subnet. Our Subnet Calculator can help you plan and verify these network ranges.

When working with cross-domain authentication, it is important to verify the domain identity of your token issuers. Use our Domain Dashboard to inspect SSL certificates, DNS configuration, and security headers for any domain referenced in your JWT claims.

However, JWTs are not always the right choice. For a detailed comparison of JWTs versus server-side sessions, see our guide on JWT vs Session Authentication.

Common Pitfalls

Understanding JWTs means understanding their limitations. Here are the most common mistakes developers make:

• Treating base64url as encryption: Encoding is not encryption. The payload is trivially readable by anyone.
• Using long-lived tokens: A JWT that never expires is a permanent credential that cannot be revoked. Always set reasonable exp values.
• Ignoring algorithm validation: Always validate the alg header against a whitelist of expected algorithms. The infamous “alg:none” vulnerability exploits servers that accept any algorithm.
• Storing sensitive data in the payload: Remember, JWTs are signed, not encrypted. Keep the payload minimal.
• Not validating all claims: Always check exp, iss, and aud at minimum. Skipping these checks opens the door to token misuse.

For a comprehensive list of security recommendations, read our JWT Security Best Practices guide.

Try It Yourself

The best way to understand JWTs is to work with them hands-on. Our JWT Decoder lets you paste any JWT and instantly see its decoded header, payload, timing information, and security analysis -- all processed entirely in your browser for privacy.