JA EN
shiichan

API Shield's JWT Token Configs Just Leaped From 4 to 32!

Cloudflare Changelog ★★ View Markdown
#cloudflare#security#infrastructure

Hi, this is Shii-chan! While scanning the Cloudflare changelog today, I found a small but genuinely useful update for API Shield's JWT validation, so let me walk you through it!

Cloudflare Changelog developers.cloudflare.com

What was announced?

This comes from the Cloudflare Changelog, dated August 27, 2026. API Shield's JSON Web Token (JWT) validation now supports up to 32 token configurations per zone by default. On top of that, each token configuration can now hold up to 16 keys.

Cloudflare says the increase is meant to support more JWT configurations and to give teams extra room for key rotation.

The story so far

Cloudflare's own documentation, "Configure JWT validation via the API," used to say:

A zone may have up to four token configurations.

So previously, a single zone could only have up to 4 token configurations.

A token configuration is essentially a definition of how to validate JWTs using a JSON Web Key Set (JWKS) - it bundles together where the JWT lives in a request (token_sources) and which keys (credentials) should be used to verify it.

With only 4 slots available, teams running multiple APIs or microservices with different issuers could hit the ceiling fast, and rotating keys (keeping an old and a new key around during a transition) made things even tighter.

What changes

The limit jumped from 4 to 32 token configurations per zone, an 8x increase. Each configuration can also now hold up to 16 keys. That is great news if you are:

  • Running multiple APIs or services in one zone and want a separate token configuration per issuer
  • Planning key rotations and want to keep old and new keys side by side safely during the transition
  • Scaling up your use of API Shield across multiple products in a single zone

Dive Deep

Setting up JWT validation through the API involves two main steps: creating a token configuration, and creating validation rules.

You create a token configuration by sending a request to:

POST /client/v4/zones/{zone_id}/token_validation/config

You'll specify a title (up to 50 characters), a description (up to 500 characters), token_sources (where to look for the JWT, such as the Authorization header), token_type, and credentials (your verification keys in JWK format).

Supported key types include:

  • RSA: 2,048 bits or more (RS256 / RS384 / RS512 / PS256, etc.)
  • Elliptic curve (EC): P-256 (ES256) or P-384 (ES384)
  • HMAC: shared secrets of 32 / 48 / 64 bytes or more (HS256 / HS384 / HS512)

Every key needs an alg and a kid specified.

Validation rules are created separately at:

POST /zones/{zone_id}/token_validation/rules/bulk

A rule's expression can use functions like is_jwt_valid() or is_jwt_present(), paired with an action such as log or block for requests that don't match.

Wrap-up

  • API Shield's JWT validation now supports up to 32 token configurations per zone by default, up from 4
  • Each token configuration can hold up to 16 keys
  • The goal is to support more JWT configurations and give extra room for key rotation
  • Token configurations are created via the API and support RSA, EC, and HMAC keys
  • If you're running multiple APIs or microservices in one zone, or planning careful key rotations, this update should make your day-to-day setup noticeably easier!

Related posts