Cloudflare API Shield: The Positive Security Model for APIs

Short answer: A WAF asks “does this look like an attack?”; API Shield asks “is this the request my API is supposed to receive?”. Its parts answer different questions — mTLS and JWT validation settle identity, schema validation checks the request against an uploaded OpenAPI contract, Discovery builds the endpoint inventory, Sequence Analytics models call order, and Volumetric Abuse Detection suggests per-session thresholds. None of them mitigate traffic on their own: each produces a signal that a WAF custom rule or a rate limiting rule has to act on. API Shield is an Enterprise paid add-on; mTLS with a Cloudflare-managed CA is available on every plan.

Why a negative security model struggles with APIs

Managed WAF rules work from known-bad patterns: injection syntax, exploit payloads, scanner fingerprints. That works for the attack classes it was written for, and it keeps working after you adopt API Shield — the two are stacked, not swapped.

The problem is that the API incidents that cost money rarely contain an attack payload. Consider what an abuse incident actually looks like in the logs:

Incident	What the request looks like	Why a negative model misses it
Shadow API	A valid path nobody knew was public	No signature to match; nobody wrote a rule for an endpoint that was never catalogued
Credential abuse	Correct credentials, correct JSON, plausible rate	Nothing in the payload is malicious; only the identity is wrong
Object-level abuse (BOLA)	GET /api/invoices/{id} with a valid token	The request is well-formed and authorised; only the object is not the caller’s

In all three the request is syntactically indistinguishable from legitimate traffic. The distinguishing evidence is elsewhere: is this endpoint in my contract, does this caller hold a credential I issued, is this call sequence one my clients actually produce, is this session’s volume normal for this operation? That is a positive model — you declare what is allowed and treat everything else as unknown.

What a positive security model means at the edge

Three dimensions can be asserted before a request is worth forwarding:

1. Structure — the endpoint, method, path and query parameter shapes, and the request body match a published contract.
2. Identity — the caller holds a credential you issued: a client certificate, or a signed token that has not expired or been altered.
3. Behaviour — the call order and the per-session volume match what this operation normally sees.

A negative model says “block what I recognise as bad”. A positive model says “allow what I recognise as mine”. For APIs the second question is the one that catches the expensive failures, because API abuse is usually well-formed.

What is actually in API Shield

The name covers several components that are frequently conflated. Each answers one question, and each has a separate availability statement — which is why “we have Enterprise, so we have API Shield” is not a safe assumption.

Component	Question it answers	What it produces	Availability
Session identifiers	Which client session does this request belong to	Session context for every downstream feature	Requires an API Shield subscription or eligible trial; up to 10 identifiers
Endpoint Discovery	Which endpoints do I actually expose	Candidate and shadow operations	Requires the paid API Shield add-on
Schema Validation	Does this request match my contract	cf.schema_validation.uploaded.violated	Schema upload limits follow your zone plan; Enterprise required for Log action
mTLS	Does the client hold a certificate I trust	Certificate validation at the edge	All plans with a Cloudflare-managed CA; uploaded CAs are Enterprise-only, max 5
JWT Validation	Is this token expired, altered, or not yet valid	cf.api_gateway.tokens.valid and verified claims	All API Shield customers; Enterprise preview available
Sequence Analytics	Is this call order one my clients produce	Precedence-scored sequences, up to 9 operations	All API Shield customers; trial available on Pro and Business
Volumetric Abuse Detection	Is this session’s volume normal for this operation	Per-session threshold with p50/p90/p99 and confidence	Enterprise customers only

Two of these deserve more than a table row.

Schema Validation 2.0 is a detection, not a control. Uploading an OpenAPI schema produces an always-on detection. Cloudflare’s documentation is explicit that the detection does not mitigate traffic by itself: you review results in Profile Analysis, then enforce with a WAF custom rule using cf.schema_validation.uploaded.violated. Teams that upload a schema and wait for blocks to appear are waiting for something that is not coming.

Volumetric Abuse Detection changes the unit of limiting. Traditional rate limiting counts requests per IP or per characteristic over a fixed window. This feature groups requests into 10-minute buckets per session, analyses seven days of traffic, and returns a recommended threshold with percentile values and a confidence classification for each operation. Session-based counting reduces the false positives that appear when many legitimate users share an egress IP. Enabling session-based rate limits requires an Advanced Rate Limiting subscription.

Where detection ends and enforcement begins

The most common deployment mistake is treating these features as switches that block traffic. They are signal producers; the rule is what acts.

A deployment order that avoids dead ends

Step 1: session identifiers. Configure them before anything else. You can define up to 10, as a cookie, an HTTP header or a JWT claim. If you configure nothing and the Authorization header appears on more than 1% of eligible sampled requests with 2xx responses, Cloudflare will configure that header for you — and it will not overwrite an existing configuration. Note the dependency: Discovery, Sequence Analytics, Sequence Mitigation and rate limit recommendations all consume this setting, so skipping it silently disables the analytical features.

Step 2: Discovery, as inventory rather than protection. Discovery builds an endpoint map from sampled traffic using path-structure heuristics, grouping /api/profile/238 and /api/profile/392 into /api/profile/{var1}. Read the thresholds before you plan around it: for an endpoint to appear, it must return 2xx from the edge, must not originate from a Cloudflare Worker, and must receive at least 500 requests within a continuous 10-day period. Low-traffic internal endpoints will simply not show up. Discovery also has to be active at both the account and the zone level; an account-level subscription not assigned to the zone produces nothing.

Step 3: upload the OpenAPI schema, then enforce it. Cloudflare accepts OpenAPI v3.0 semantics — v3.1 uploads succeed when they use v3.0-compatible semantics, while v3.1-only semantics and OpenAPI 2.0 are not supported. Endpoints must exist as saved operations in Web Assets. Run the detection in Log first: read violations in Profile Analysis, fix the schema where the schema is wrong, and only then move to Block. Also add a fallthrough rule — the dashboard ships a Mitigate API requests to unidentified endpoints template, which uses cf.api_gateway.fallthrough_detected to catch requests that do not match any saved operation. That rule is what actually closes shadow APIs.

Step 4: identity. For machine-to-machine traffic — partner integrations, IoT fleets, service accounts — mTLS binds the credential to a certificate rather than a shared string, and it works on every plan with a Cloudflare-managed CA. It also covers gRPC. For user-facing traffic, JWT validation checks signature and expiry at the edge and exposes verified claims to your rules. Two operational details matter: token configurations do not fetch or refresh keys from a JWKS URL, so rotating keys must be pushed in; and browsers send credential-less OPTIONS pre-flight requests, so add or http.request.method eq "OPTIONS" to JWT rules or you will break CORS clients.

Step 5: behaviour. With a session identifier and saved operations in place, Sequence Analytics surfaces ordered call patterns ranked by precedence score, estimated from the last 24 hours of data, up to nine operations long. Use it to find the journeys that matter and confirm with your own developers whether the final operation must always be preceded by the earlier ones. Volumetric Abuse Detection then gives you per-operation, per-session thresholds — start in log mode when the confidence classification is low.

Step 6: keep the application-layer controls. The edge cannot decide whether a tenant may read a specific object, cannot hold a global quota, and cannot convert a request into a cost. Those stay in your code.

What API Shield does not do

Publishing the limits is the point of this article, so here they are plainly:

Limit	Detail
Response validation	Not supported. Validation applies to requests, not to what your API returns
Schema features	No support for responses, external references, non-basic path templating, or uniqueItems
Object-type parameters	Not currently validated
Body validation size	Free 1 KiB, Pro 8 KiB, Business 8 KiB, Enterprise 128 KiB — separate from the WAF body inspection size
Discovery coverage	Endpoints under the 500-request / 10-day threshold never appear
Sequence length	Limited to nine operations
JWT location	Header or cookie only; JWTs sent in a POST body are not validated without contacting your account team
Global quotas	Rate limit counters accumulate per data center, so no edge rule gives you a network-wide ceiling
Business authorisation	Object-level access control is application logic

Two of these are worth restating because they cause the most disappointment. Schema validation checks shape, not meaning — a request can satisfy the contract and still be an unauthorised read of someone else’s record. And a shared egress IP is not a session: per-session counting is precisely what fixes NAT and proxy collisions, but it depends on a session identifier you configured, not on something Cloudflare infers.

Plan and pricing boundaries

The table below is summarised from Cloudflare’s API Shield plans documentation; treat the console as authoritative.

	Free	Pro	Business	Enterprise without API Shield	Enterprise with API Shield
Saved endpoints	100	250	500	3,000	10,000
Enabled uploaded schemas	5	5	10	10	10
Combined size of enabled schemas	200 KiB	500 KiB	2 MiB	5 MiB	10+ MiB
Rule action	Block only	Block only	Block only	Log or Block	Log or Block

Three consequences follow from that table and from the availability statements:

• API Shield is an Enterprise-only paid add-on. Upgrading the zone plan does not include it. Cloudflare’s documentation also notes that Enterprise customers can preview API Shield as a non-contract service, with full access and no metered usage fees during the preview — which is the practical way to test whether your schemas and session identifiers are in good enough shape to justify the purchase.
• Block-only below Enterprise changes how you roll out. Without a Log action you cannot observe violations before enforcing them, so on Free, Pro or Business the honest workflow is to build the contract carefully, then enforce — or to use WAF Application Profiles with Schema Learning, which derives a profile from traffic instead of an uploaded file.
• mTLS is the exception that works everywhere. Anyone can set up mutual TLS with a Cloudflare-managed certificate authority. Uploading your own CA is limited to Enterprise customers, five CAs, with higher limits available on request. If your immediate problem is “our partner integrations share one long-lived key”, that is solvable without an add-on.

When this pays off, and when it does not

Worth the effort when: you expose a documented API to third parties or partners; you have mobile, desktop or IoT clients you cannot patch quickly; you run several API subdomains with overlapping operations; you are facing an audit that asks for an endpoint inventory; or your contracts are stable enough that maintaining an OpenAPI file is cheaper than investigating incidents.

Poor fit when: the API is a handful of internal endpoints with one consumer — the schema governance cost exceeds the risk; traffic is far below the Discovery threshold, so inventory stays incomplete; your protocol is binary and outside what schema validation covers, in which case mTLS plus application-layer checks carry the load; or nobody owns the OpenAPI file, because a stale contract enforced at the edge blocks legitimate callers faster than it blocks attackers.

A reasonable middle path for teams not ready to buy: configure session identifiers, use Schema Learning to derive a profile from real traffic, enforce the fallthrough rule for unknown endpoints, and put mTLS in front of machine-to-machine integrations. That sequence needs no add-on and covers the two failure modes — unknown endpoints and shared credentials — that cause most API incidents.

FAQ

Is API Shield included with an Enterprise plan? No. Cloudflare documents the full API Shield security suite as an Enterprise-only paid add-on, and you subscribe by upgrading to Enterprise and contacting your account team. Enterprise customers can preview it as a non-contract service with full access and no metered usage fees. Individual components differ: mTLS with a Cloudflare-managed CA works on every plan, and Sequence Analytics offers a trial to Pro, Business and Enterprise customers who have not purchased API Shield.

Does uploading an OpenAPI schema block bad requests automatically? No. Schema Validation produces an always-on detection, and Cloudflare states that the detection does not mitigate traffic by itself. You review violations in Profile Analysis and then enforce with a WAF custom rule matching cf.schema_validation.uploaded.violated. On Free, Pro and Business the only available action is Block; Log requires Enterprise, which is why a log-then-enforce rollout depends on the plan.

Can we use mTLS without buying API Shield? Yes. All plans can configure mTLS with a Cloudflare-managed certificate authority, and it is not gated behind API Shield — the mTLS documentation says explicitly that API Shield is not required. Uploading up to five non-Cloudflare CAs is an Enterprise capability. mTLS also supports gRPC-based APIs, which matters for service-to-service traffic that does not speak JSON.

Does API Shield fix broken object-level authorisation? No. Schema validation confirms that a request has the right shape; it cannot know whether the authenticated caller is allowed to read that specific object. Object-level authorisation is application logic. The same applies to global quotas — rate limit counters accumulate per data center, so a network-wide ceiling has to be implemented in your own stack.

Which OpenAPI versions can we upload? Cloudflare accepts OpenAPI v3.0 semantics, including all 3.0.x patch versions, in YAML or JSON. Uploads using v3.1 can succeed when they rely on v3.0-compatible semantics, but v3.1-only semantics are not supported and OpenAPI 2.0 is not supported at all. External $ref references are not supported either, so bundle multi-file schemas into one file before upload.

When is API Shield not worth buying? When your API surface is small and single-consumer, when no one maintains an accurate OpenAPI file, or when your traffic sits below Discovery’s threshold of 500 requests per endpoint in a continuous 10-day window. In those cases session identifiers, Schema Learning from real traffic, a fallthrough rule for unknown endpoints and mTLS for machine-to-machine callers deliver most of the value without the add-on.

Related reading

• How to Mitigate API Key Abuse and Unauthorized Access
• How to Prevent API Abuse in AI SaaS
• How to Choose an Enterprise Web Application Firewall
• How to Distinguish Legitimate Users from Malicious Bots

If you want a second opinion on whether a positive model fits your API surface, start from your existing contract and traffic rather than from a feature list — review the architecture with us.