🎫
← Back to Guides

JWT Token Structure Explained: Header, Payload, and Signature

· Tags: jwt-structure, jwt-header, jwt-payload, jwt-signature, json-web-token

JWT Token Structure Explained

Every JSON Web Token (JWT) is a compact, URL-safe string that carries claims between two parties. Understanding its internal structure is essential for any developer working with token-based security.

The Three Parts of a JWT

A JWT consists of three parts separated by dots (.):

header.payload.signature

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Each part is base64url-encoded JSON. A JWT is signed, not encrypted — anyone can decode and read its contents.

Part 1: The Header

The header contains metadata about the token — the signing algorithm and token type.

| Field | Description | Example Values | |-------|-------------|----------------| | alg | Signing algorithm (required) | HS256, RS256, ES256 | | typ | Token type (optional) | JWT | | kid | Key ID (optional) | "key-1" |

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

The alg field tells the verifier which algorithm created the signature. An algorithm mismatch — or accepting alg: "none" — is a common JWT security vulnerability.

Part 2: The Payload

The payload contains claims about the user and metadata. Claims fall into three categories:

Registered Claims

| Claim | Full Name | Purpose | |-------|-----------|---------| | iss | Issuer | Who issued the token | | sub | Subject | Identifies the user | | aud | Audience | Intended recipient | | exp | Expiration | Token expiry timestamp | | nbf | Not Before | Token not valid before this time | | iat | Issued At | Token creation timestamp | | jti | JWT ID | Unique token identifier |

Decoded Payload Example

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622,
  "iss": "https://auth.example.com"
}

Public claims are defined in the IANA registry or use collision-resistant URIs. Private claims are custom claims agreed upon between issuer and consumer.

Part 3: The Signature

The signature is created by combining the encoded header, encoded payload, and a secret key using the algorithm from the header. It serves two purposes:

  1. Integrity — confirms the token was not modified after signing.
  2. Authentication — proves the token was signed by the expected party.

HS256 Signature Creation

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

RS256 Signature Creation

RSASHA256(
  base64urlEncode(header) + "." + base64urlEncode(payload),
  privateKey
)

Base64url vs Standard Base64

| Aspect | Standard Base64 | Base64url | |--------|-----------------|-----------| | Char 62 | + | - | | Char 63 | / | _ | | Padding | = | Omitted |

This encoding ensures JWTs are safe for HTTP headers, query parameters, and URL paths without percent-encoding.

Complete JWT Creation Process

  1. Create the header JSON and base64url-encode it.
  2. Create the payload JSON and base64url-encode it.
  3. Concatenate with a . separator.
  4. Sign with the chosen algorithm and secret.
  5. Base64url-encode the signature.
  6. Concatenate all three parts with . separators.

Security Considerations

  • Never store secrets in the payload. The payload is encoded, not encrypted.
  • Always validate the signature. Without verification, anyone can forge tokens.
  • Check the alg header. Reject alg: "none" and algorithm downgrade attempts.
  • Set short expiration times. Use exp claims in minutes or hours, not months.

Decode a JWT Token Online

Use the JWT decoder tool to examine any token. Paste it and instantly see the decoded header, payload, and signing algorithm. All processing happens in your browser.

JWT Token Structure Explained: Header, Payload, and Signature - CoolTool