JWT Header Explained — Algorithm, Type & Key ID Fields

1. What Is the JWT Header?
2. Header Fields Reference
3. The alg Field — Choosing an Algorithm
4. The kid Field — Key Rotation
5. Header Examples by Use Case
6. Header Security Considerations
7. Header vs Payload

1. What Is the JWT Header?

The header is the first part of a JSON Web Token — a small JSON object that describeshow the token is signed and encoded. It's also known as the JOSE (JSON Object Signing and Encryption) header.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.payload.signature

HeaderPayloadSignature

Decoding the blue part gives you a JSON object like:

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

The header is intentionally small. Its only job is to tell the JWT library which algorithm to use for signature verification and, optionally, which key to select.

2. Header Fields Reference

Field	Name	Required	Description
alg	Algorithm	Yes	The cryptographic algorithm used to sign the token
typ	Type	Optional	The token type — always `"JWT"` for JSON Web Tokens
kid	Key ID	Optional	Identifies which key to use when multiple keys are available
jku	JWK Set URL	Optional	URL pointing to a set of JSON Web Keys
jwk	JSON Web Key	Optional	The public key embedded directly in the header
x5u	X.509 URL	Optional	URL for the X.509 certificate chain
x5c	X.509 Chain	Optional	X.509 certificate chain embedded in the header
cty	Content Type	Optional	Used for nested JWTs — set to `"JWT"` when the payload is itself a JWT

In practice, most JWTs only use alg and typ. The other fields appear in more complex systems that use key rotation or certificate chains.

3. The `alg` Field — Choosing an Algorithm

The alg field is the most important header parameter. It determines which cryptographic algorithm is used to create and verify the signature.

HMAC (Symmetric)

Same secret for signing and verifying

{ "alg": "HS256", "typ": "JWT" }  // SHA-256
{ "alg": "HS384", "typ": "JWT" }  // SHA-384
{ "alg": "HS512", "typ": "JWT" }  // SHA-512

RSA (Asymmetric)

Private key signs, public key verifies

{ "alg": "RS256", "typ": "JWT" }  // RSASSA-PKCS1-v1_5 + SHA-256
{ "alg": "RS384", "typ": "JWT" }  // RSASSA-PKCS1-v1_5 + SHA-384
{ "alg": "RS512", "typ": "JWT" }  // RSASSA-PKCS1-v1_5 + SHA-512

ECDSA (Asymmetric)

Elliptic curve — smaller keys, same security

{ "alg": "ES256", "typ": "JWT" }  // P-256 curve + SHA-256
{ "alg": "ES384", "typ": "JWT" }  // P-384 curve + SHA-384
{ "alg": "ES512", "typ": "JWT" }  // P-521 curve + SHA-512

For a detailed comparison of when to use each algorithm, see our JWT algorithms guide.

4. The `kid` Field — Key Rotation

The kid (Key ID) field tells the verifier which key to use when multiple signing keys exist. This is essential for key rotation — the process of periodically changing signing keys without invalidating all existing tokens.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "2024-signing-key-v2"
}

When the server receives this token, it looks up key "2024-signing-key-v2" from its key store (often a JWKS endpoint) and uses that specific key to verify the signature. This allows old tokens signed with "2024-signing-key-v1" to remain valid while new tokens use the updated key.

Common pattern: Identity providers like Auth0, Okta, and Google publish their public keys at a JWKS (JSON Web Key Set) endpoint. The kid in the JWT header matches a key in the JWKS, allowing automatic key selection.

5. Header Examples by Use Case

Simple API Authentication

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

Minimal header — single service, shared secret, no key rotation needed.

Microservices with Key Rotation

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "auth-service-key-2024-q4"
}

Asymmetric signing with key ID for rotation across multiple services.

OpenID Connect ID Token

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "abc123def456",
  "jku": "https://auth.example.com/.well-known/jwks.json"
}

Includes JWKS URL for automatic public key discovery.

6. Header Security Considerations

The "alg: none" Attack

Setting "alg": "none" means the token has no signature. Early JWT libraries accepted these tokens without verification, allowing attackers to forge arbitrary tokens. Modern libraries reject "none" by default, but always ensure your library is configured to require a specific algorithm.

Algorithm Confusion Attack

If a server expects RS256 (asymmetric) but doesn't enforce the algorithm, an attacker can change the header to HS256 (symmetric) and sign the token using the server's public RSA key as the HMAC secret. Always validate that the algorithm in the header matches what you expect.

Best Practice

Never trust the alg header blindly. Configure your JWT library with an explicit list of allowed algorithms and reject tokens that don't match. Most modern libraries do this by default.

For more JWT security topics, see our security best practices guide.

7. Header vs Payload

Aspect	Header	Payload
Purpose	How to verify the token	What the token says
Read by	JWT library	Your application
Size	2-4 fields	5-20+ fields
Custom fields	Rare	Common
Security concern	Algorithm confusion	Sensitive data exposure

Learn more about the payload in our JWT payload guide.

Inspect Your JWT Header

Paste any JWT to instantly see its decoded header — algorithm, type, key ID, and all fields.

Go to JWT Decoder Algorithm Comparison

Table of Contents