Cloudflare API Shield JWT validation and mutual TLS (mTLS) authenticate API clients in different ways. JWT validation checks a token found in a configured request header or cookie. mTLS checks whether the request presents a valid client certificate. The better fit depends on how your clients authenticate and where you need enforcement to apply.
This comparison covers Cloudflare API Shield documentation updated in 2026, including JWT support for HS256, HS384, and HS512 added on August 25, 2026. It is a research-based guide, not a hands-on test or performance review.
JWT validation or mTLS?
| Choose | When the documented model fits |
|---|---|
| JWT validation | Your clients already send signed tokens in configured request headers or cookies, and you need to validate claims or apply rules to selected scopes. |
| mTLS | Your clients can use certificates and you need Cloudflare to block requests that lack a valid client certificate for configured hosts or paths. |
Cloudflare describes mTLS use cases that include mobile applications, IoT devices, services, and gRPC-based APIs. JWT validation supports tokens issued with asymmetric RSA or elliptic-curve keys, or with symmetric HMAC keys. These documented examples do not establish that every client, API framework, or browser workflow supports either method.
How Cloudflare API Shield JWT validation works
A JWT token configuration tells Cloudflare where to look for a token and how to verify it. Supported token sources are request headers and cookies, with up to four configured sources. If a request has more than one configured source, Cloudflare uses only one. JWTs sent in a POST body are outside the documented limitation; Cloudflare says to contact its account team for that case.
The configuration contains verification credentials. RSA supports RS256, RS384, RS512, PS256, PS384, and PS512, with RSA keys of at least 2,048 bits. EC supports ES256 with curve P-256 and ES384 with curve P-384. HMAC supports HS256, HS384, and HS512, requiring symmetric secrets of at least 32, 48, and 64 bytes respectively. Each JWK needs an alg and kid value. Cloudflare’s changelog records the HMAC algorithm support as an August 25, 2026 change.
After a token configuration exists, Cloudflare checks every request in the zone for a JWT at the configured locations and validates any token it finds. A separate rule determines what happens next. Cloudflare recommends WAF custom rules for new zone-wide policies based on verified claims. Token validation rules are available when enforcement must apply only to specific operations in Endpoint Management.
JWT enforcement choices and browser caveat
For operation-specific enforcement, Cloudflare documents options for requiring a token or ignoring missing tokens while still validating tokens that are present. A non-compliant action can apply when a token is invalid or required but missing. This creates a useful rollout boundary: a policy can validate tokens without requiring every request to contain one, when that is appropriate for the selected rule.
Browser applications need a separate check. Cloudflare says browser CORS pre-flight requests use the OPTIONS method and do not include authentication headers or cookies. If browsers are valid API clients, Cloudflare recommends adding an exception for OPTIONS requests to JWT validation rules so those pre-flight requests are not blocked. The supplied documentation does not establish that this exception is appropriate for every API, so the API’s own CORS policy still needs review.
How Cloudflare API Shield mTLS works
mTLS uses client certificates so the client and server can establish mutual trust. Cloudflare says it can be used for clients such as mobile applications, IoT devices, and services, and that it supports gRPC-based APIs.
Cloudflare’s configuration documentation states that specifying API hosts in mTLS authentication blocks requests that do not have a client certificate for mTLS authentication. The documented prerequisites include an origin certificate matching the hostname, a client certificate, client configuration using the Cloudflare-issued certificate, and mTLS enabled for a host in the zone. Cloudflare’s example says wildcard origin certificates such as *.example.com are not supported for this prerequisite.
An mTLS rule can target a URI path and optionally hostnames. With a Block action, requests without a valid client certificate are blocked. Cloudflare recommends checking the issuer Subject Key Identifier as well. Without that check, its documentation says any valid client certificate is accepted regardless of the issuing certificate authority. A separate expression can also check whether a client certificate was revoked.
mTLS availability boundary
All Cloudflare plans can set up mTLS with a Cloudflare-managed certificate authority. Enterprise customers can upload up to five non-Cloudflare certificate authorities; Cloudflare says to contact its account team for higher limits. This is a documented certificate-authority limit, not a claim that all mTLS configurations have identical capabilities across plans.
Credential and certificate differences
| Area | JWT validation | mTLS |
|---|---|---|
| Client proof | A signed JWT found in a configured header or cookie. | A valid client certificate presented for mTLS authentication. |
| Configuration material | JWKS, asymmetric public keys, or HMAC secrets with documented algorithm and length requirements. | Client certificates, a certificate authority arrangement, and the documented hostname and origin prerequisites. |
| Rule boundary | WAF custom rules can apply zone-wide; token validation rules can target Endpoint Management operations. | Rules can target configured hosts and URI paths. |
| Important limitation | Documented token locations are headers and cookies, not ordinary POST bodies. | Cloudflare documents plan and certificate-authority limits, plus a Yubikey PKCS#11 browser limitation. |
A practical selection process
- List the client types that must call the API. If they use signed JWTs in headers or cookies, JWT validation matches the documented input model. If they can use client certificates, mTLS is the documented certificate-based option.
- Define the enforcement boundary. Use the JWT rule model when you need verified claims, zone-wide WAF custom rules, or selected Endpoint Management operations. Use mTLS host and path rules when the certificate requirement itself should block unauthenticated requests.
- Check rollout exceptions. For JWT, decide how missing tokens should be handled and account for anonymous browser OPTIONS pre-flight requests. For mTLS, confirm the origin certificate, client certificate, hostname, certificate authority, and any issuer or revocation checks.
- Test the intended policy in your own change process before applying a blocking action. The supplied sources document configuration behavior but provide no test results for your API, clients, browser application, or origin.
Where the two methods can coexist
The supplied Cloudflare excerpts document JWT validation and mTLS as separate API Shield authentication features. They establish each feature’s inputs and rule boundaries, but they do not describe a general combined JWT-and-mTLS request sequence or guarantee how every combination behaves. If an API needs both controls, verify the intended interaction in current Cloudflare documentation and in a controlled environment before enforcing it.
Bottom line
Choose JWT validation when token-based identity, claims, and flexible rule scope are central to the API design. Choose mTLS when certificate-based client identity and host or path blocking are the central requirement. For browser clients, review the documented OPTIONS pre-flight behavior before enforcing JWT presence. For mTLS, check the certificate, hostname, origin, certificate-authority, issuer, and revocation requirements that apply to your configuration.
Research method and limitations
This article was prepared only from the supplied public Cloudflare API Shield excerpts retrieved on September 23, 2026, plus the supplied NGINX competitor excerpts for coverage review. Cloudflare’s JWT API passage was partially truncated, so this article uses only its visible statements. The competitor excerpts were not used as technical authority. No hands-on access, lab test, benchmark, comprehensive plan review, or independent client compatibility test was available.
Text version of the diagrams
- JWT validation vs mTLS: Client proof — Signed JWT or certificate; Setup material — Keys or certificate chain; Rule boundary — Claims, hosts, or paths
- Rollout boundaries: Browser clients — OPTIONS may lack credentials; JWT rollout — Ignore or require presence; mTLS checks — Host, issuer, revocation
