API Shield — Full Curriculum

Personal study reference, not customer-facing. Built to answer anything that could come up on a real call — what it actually does, how each feature works mechanically, the plan reality (Enterprise-only), and the single most important and most-missed fact: almost everything here only detects, it doesn't block, until you wire up a separate WAF rule. Every fact below is sourced from live Cloudflare docs (full list at the bottom).

Module 1Fundamentals — what API Shield actually is

API Shield is Cloudflare's API security and management product — discovery, a positive security model (schema, mTLS, JWT), and abuse/vulnerability detection, all at the same edge as your WAF and bot management. The single most important mental model to internalize before anything else:

Why API security is a distinct problem from WAF

Traditional WAFs catch payload-level attacks — SQL injection, XSS — inside a request. They don't catch a script enumerating /users/1, /users/2, /users/3 at machine speed, a malformed JSON body with an extra trusted field, or an endpoint nobody on the security team even knows exists. API Shield is built specifically for the shape and behavior of API traffic, not just payload content — both run in the same Cloudflare engine and are meant to complement each other, not replace one another.

The OWASP API Security Top 10 — what maps to what

Full feature list

Discovery · Schema Validation · Schema Learning · JWT Validation · mTLS · Sequence Analytics · Sequence Mitigation · Volumetric Abuse Detection · Authentication Posture · BOLA vulnerability detection · Vulnerability Scanner (DAST, open beta) · Zombie API detection. All of these live under the umbrella of Web Assets in the dashboard (Security → Web Assets → Operations) — Cloudflare's newer, consolidated inventory view that replaced the older per-feature dashboard pages.

Module 2Discovery & endpoint management

"You can't protect what you don't know exists." Most companies cannot list every API endpoint they expose — developers ship new ones weekly, old ones never get decommissioned, there's no central inventory. Discovery solves the inventory problem first, before anything else in this document makes sense.

How it actually works

Cloudflare applies heuristic path normalization to sampled, qualifying traffic — grouping requests by path structure and variable-like segments. api.example.com/profile/238 and api.example.com/profile/392 get grouped into one endpoint: /profile/{var1}. The {varN} placeholders are generated identifiers, not semantic names. Cloudflare can also consolidate the same normalized path across compatible subdomains — e.g. us-api./de-api./fr-api.example.com/api/v1/users/{var1} can collapse into {hostVar1}.example.com/api/v1/users/{var1}.

Operation states — this is the part people get wrong

You do not need to save every discovered operation — candidate operations already provide useful matching context on their own. Only promote an operation to full (via "Learn profile") when you actually want the deeper protections.

Discovery requirements (all must be true)

• Active API Shield subscription at both account and zone level — account-level entitlement alone does nothing for a zone it isn't assigned to
• Request returns a 2xx response from the Cloudflare edge
• Path is outside /cdn-cgi
• Request does not originate directly from a Cloudflare Worker (Worker-based test harnesses/traffic simulators don't count toward thresholds)
• Endpoint receives at least 500 requests within a continuous 10-day period

Discovery uses multiple signals including machine learning and any configured session identifiers (Module 4) — a session identifier is optional for Discovery to function, but improves its accuracy.

Once it's enabled — what to actually do, step by step

This is the practical day-1 checklist for a customer who just turned on API Shield. Everything below happens in one place: Security → Web Assets → Operations.

1. Don't expect anything on day one. Discovery needs an endpoint to clear the requirements above (500+ requests in a continuous 10-day window, 2xx responses, outside /cdn-cgi) before it shows up at all. Set that expectation with the customer up front — "nothing populated yet" the first day is normal, not broken.
2. Check the Discovery tab first. This is where newly-seen endpoints accumulate automatically — no action required to get them here. They arrive in shadow or candidate state (see the table above).
3. Decide what's worth promoting to Full. You do not need to act on every discovered operation. Walk through the list with the customer and identify the endpoints that actually matter — auth, payments, anything handling per-user data — and promote those via "Learn profile" from the operation's overflow menu. This is also the prerequisite step for Schema Learning (Module 3) and for Bot/API-specific Custom Rules later.
4. Check Security → Analytics for live data. Once operations are flowing, this is where you confirm API Shield is actually seeing traffic — request volume per operation, response codes, and (once a profile exists) conformance/violation trends.
5. Check the Suspicious Activity card for BOLA findings — do this even before step 3. BOLA (Broken Object Level Authorization) detection runs automatically for any Enterprise account with an active API Shield subscription — no setup, no beta, no extra cost. It's easy to miss because it's not a toggle anyone has to flip. Worth checking on day one: a customer with existing per-user endpoints (profile IDs, order IDs, account IDs in the URL) may already have findings waiting, which is a strong, concrete "here's value you didn't know you had" moment in a QBR or check-in call.

Module 3Schema Validation & Schema Learning

Both of these feed the same underlying profile type — a Schema Profile, under the broader "Application Profiles" framework. They're two different ways of getting there.

Multiple uploaded schemas can be active simultaneously. If a new schema covers an operation already covered by an existing one, it replaces the validation definition for that operation only — everything else keeps its prior definition.

Turning detection into an actual block — the real WAF rule

Neither Schema Learning nor Schema Validation blocks anything by default — per Module 1's core point, this is pure detection until you add a Custom Rule:

// Block anything that violates a learned schema, scoped to one path
cf.schema_validation.learned.violated and http.host eq "api.example.com" and starts_with(http.request.uri.path, "/v1/orders/")

// Combine an uploaded-schema violation with Bot Score for extra confidence
cf.schema_validation.uploaded.violated and cf.bot_management.score lt 10

Cloudflare's own rollout guidance: review production traffic and sampled violation reasons in Security Analytics first, then create the Custom Rule once you're confident it only catches what you expect.

The fallthrough rule — protecting the endpoints you don't know about yet

A fallthrough rule is a WAF Custom Rule that matches any request that doesn't match a saved operation — i.e., genuinely unknown/undocumented traffic. Requests matching a candidate operation still count as matching the fallthrough rule (candidates aren't "known" in the full sense). This is the real answer to "what happens to the APIs we don't even know exist yet" — a fallthrough rule gives you a deliberate catch-all policy for them instead of silence.

Mass assignment, concretely

Classic attack: a login schema expects {"username", "password"}, attacker sends {"username","password","role":"admin"} hoping the backend trusts the extra field. A schema with additionalProperties: false rejects it at the edge — this is a positive-security model, so the request fails because it doesn't match the expected shape, not because anyone wrote a rule specifically about the word "role."

How to actually set this up

Upload a schema (Schema Validation):

1. Go to Web Assets page.
2. Go to the Schema validation tab.
3. Select Add validation.
4. Upload an OpenAPI schema file.
5. Select Add schema and endpoints — this adds the schema's operations to Web Assets automatically. Changes can take several minutes depending on operation count.

To manage schemas afterward: Web Assets → Schema validation tab → Schema settings → filter by "API abuse" → Active schemas. From the overflow menu on any schema you can download or delete it — deleting stops its profile evaluation but leaves the operations themselves in your inventory.

Learn a schema instead (Schema Learning) — covered step-by-step in Module 2's "Once it's enabled" section above.

Turn either one into an actual block (the Custom Rule):

1. Go to the Security rules page.
2. Select Create rule → Custom rules.
3. Enter a descriptive Rule name.
4. Under When incoming requests match, paste or build the expression — e.g. cf.schema_validation.learned.violated and http.host eq "api.example.com".
5. Under Then take action, choose the action.
6. Select Deploy (or Save as Draft if not ready).

Module 4Rate Limiting & Volumetric Abuse Detection

Two different things: standard Rate Limiting Rules (fixed thresholds you set yourself) and Volumetric Abuse Detection (adaptive, per-session recommendations API Shield generates for you).

Session identifiers — the foundation almost everything else depends on

A session identifier uniquely tracks one client across requests — usually the Authorization header, a cookie, or a specific JWT claim (e.g. sub or email, since the raw token value itself changes over time). You can configure up to 10 session identifiers per zone. Session identifier cookies must comply with RFC 6265 or they're rejected.

How to actually set one up

1. Go to the Security → Settings page.
2. Filter by API abuse.
3. On Session identifiers, select Configure session identifiers, then Manage identifiers.
4. Choose the type: cookie, HTTP header, or JWT claim. (A JWT claim requires a Token Configuration to already exist — see Module 7 — then specify the claim with a JSONPath expression.)
5. Name it, then select Save.

Do this early, even before you have a specific rate-limiting or Sequence Analytics need — Discovery, Volumetric Abuse Detection, Sequence Analytics, Authentication Posture, and BOLA enumeration detection all consume this same setting. One correct setting here pays off across five different features.

Session identifiers feed into far more than rate limiting — they're used by Discovery (optional signal), Sequence Analytics, Sequence Mitigation, Authentication Posture, and rate limit recommendations. Getting this one setting right early pays off across the whole product.

Volumetric Abuse Detection — how the recommendation engine actually works

Uses unsupervised learning to build a separate traffic baseline per endpoint (your /login and /reset-password endpoints naturally see very different normal volumes, and the same endpoint's "normal" can shift after a marketing campaign). It groups requests into 10-minute periods per session and uses the resulting distribution to recommend one per-session threshold per eligible operation. Needs a 7-day analysis window of sufficient eligible traffic to produce a reliable number, and at least 24 hours after adding/changing a session identifier before recommendations start appearing.

Rate limits generated this way are per-session, not per-IP — this directly reduces false positives during legitimate traffic spikes, since the limit tracks individual sessions rather than a shared IP address multiple real users might sit behind. A configured session identifier alone does not guarantee a recommendation — there must also be enough eligible traffic and a successfully calculated threshold. Actually enabling session-based rate limiting requires an Advanced Rate Limiting subscription.

Example rate limiting rules worth having ready

// Credential stuffing: tight limit on login
POST /login -> 5 requests / minute per session

// BOLA-style enumeration: moderate limit on object lookups
GET /users/:id -> 20 requests / minute per session

// Legitimate high-volume partner traffic
GET /products -> 1000 requests / minute per session

For APIs with no usable session cookie, a JA3/JA4 TLS fingerprint can serve as the counting characteristic instead — available to Bot Management customers, identifies a client across requests independent of anything in the headers.

How to actually create a rate limiting rule

1. Go to the Security rules page.
2. Select Create rule → Rate limiting rules.
3. Enter a descriptive Rule name.
4. Build the match expression (Field / Operator / Value) — e.g. URI Path equals /api/auth/login.
5. Under With the same characteristics, add what defines a unique counter — IP, a header like x-api-key, a cookie, or a JWT claim. This is the counting characteristic from Module 1's variables.
6. Under When rate exceeds, set the request threshold and period.
7. Under Then take action, pick the action and duration.
8. Select Deploy.

Module 5Vulnerability & risk detection

A cluster of detection-only features that label risky endpoints. None of these block anything by themselves — same rule from Module 1 applies throughout.

BOLA vulnerability detection

A Broken Object Level Authorization bug lets an attacker access data they shouldn't by manipulating object identifiers (user IDs, order IDs) — as dangerous as an account takeover. Cloudflare flags BOLA risk from two distinct signals:

• Enumeration — estimates how many distinct path-parameter value combinations each session (with a configured session identifier) requests from an endpoint, and compares that count against the normal distribution for that endpoint
• Parameter pollution — a second, related signal pattern common to BOLA exploitation

Findings surface in three places: Security Overview, Endpoint details (with affected sessions, IPs, and JA4 fingerprints — exportable as CSV), and Security Analytics. Confirm actual unauthorized access by cross-referencing your own API origin logs for the flagged IPs/fingerprints before assuming the worst.

Vulnerability Scanner — real DAST, not just passive detection

Launched as Open Beta: a stateful Dynamic Application Security Testing (DAST) platform that builds API call graphs simulating both attacker and legitimate-owner contexts, then sends real HTTP requests to actually test for BOLA. Set up requires your target environment, owner and attacker credentials, and an OpenAPI file with response schemas. API-only access for now — not yet in the dashboard, intended for CI/CD and programmatic integration. This is meaningfully different from everything else in this module: it's active testing, not passive traffic observation.

Zombie API detection

Automatically flags saved endpoints that haven't received traffic in 32+ days with a cf-risk-zombie label — the scan runs daily alongside other risk scans. A zombie endpoint often means deprecated, forgotten API surface that's unpatched and unmonitored. Recommended response: review and consider removing it from Endpoint Management, or use a fallthrough rule (Module 3) to actively block traffic to anything removed.

Authentication Posture

Does not validate credentials — it only reports whether your configured session identifier is present on successful requests, to catch the gap between "we think this endpoint requires auth" and "it actually enforces it." Labels update roughly once a day:

A large spike in unauthenticated-but-successful traffic on an endpoint expected to be 100% authenticated is a real signal worth escalating to your dev team immediately, not just logging.

Sensitive Data Detection (separate subscription)

Integrates with the WAF's Sensitive Data Detection ruleset to flag endpoints whose responses contain things like SSNs or credit card numbers — applies the cf-risk-sensitive label. Requires its own subscription on top of API Shield; confirm with the account team rather than assuming it's bundled in.

Module 6Sequence Analytics & Sequence Mitigation

Some attacks aren't one bad request — they're an unusual sequence of otherwise-normal-looking requests. A real user checks their balance, then transfers funds. An attacker scrapes products in random order, or hits checkout 100 times in 30 seconds. Looking at requests in isolation misses this category entirely.

Sequence Analytics

Identifies common request-order patterns automatically, ranked by a precedence score — how likely a given request is to be preceded by the other operations in that sequence. High-scoring sequences represent the normal, expected flow through your API. This requires a configured session identifier to track sequences per client over time.

Sequence Mitigation — the enforcement layer

Unlike Sequence Analytics (pure observation), Sequence Mitigation actually enforces expected request order for authenticated clients. The real workflow: use Sequence Analytics to identify your high-scoring (normal) sequences, verify the expected order with your own dev team (don't assume — confirm), then apply API Shield protections — rate limiting, Schema Validation, JWT Validation, mTLS — specifically to the endpoints inside those sequences.

Module 7mTLS & JWT Validation

The positive-security / auth-enforcement layer — reject bad actors before your application code ever has to think about them.

mTLS — how it actually works

Standard TLS only verifies the server's identity to the client; mTLS adds the reverse — the server verifies the client too, via a client certificate. By default, certificates come from a Cloudflare-managed CA at the account level (same certs work across every domain in your account, as long as mTLS is enabled per-hostname). Validation result is exposed as cf.tls_client_auth.cert_verified (true/false) plus detailed certificate fields.

Origin server wildcard certificates (*.example.com) are not supported for mTLS — the origin cert must match the specific client-certificate hostname.

How to actually set up mTLS

1. Go to the SSL/TLS → Client Certificates page.
2. Select Add Certificate (Cloudflare-managed CA is the default).
3. Either generate a private key + CSR with Cloudflare, or bring your own CSR (needed if you want to label client certificates later).
4. Choose a Certificate Validity period and continue.
5. Copy the certificate and private key immediately — they are not shown again after this step.
6. (Optional but usually required) Specify the hostnames where this cert should be accepted, in FQDN format matching your zone.
7. Select Save.

Creating the cert doesn't finish the job — you still need to install it on the actual client devices/scripts that will present it, and separately enable mTLS enforcement for each hostname that should require it.

JWT Validation — the two-part process

Always two separate pieces: a token configuration (tells Cloudflare how to find and verify JWTs — source location, JWKS/keys) and a rule that acts on the result. You do not need an operation in Endpoint Management or any rule at all just for raw validation to happen — Cloudflare checks every request in the zone at the configured source regardless; rules only control what happens with the result.

• Validates signature, expiry (exp), and not-before (nbf) — allows up to 60 seconds of clock drift between Cloudflare and the token issuer
• Verified claims exposed as http.request.jwt.claims fields for use in WAF Custom Rules
• Up to 32 token configurations per zone by default, 16 keys per configuration
• Works regardless of whether the token carries a Bearer prefix
• Rate Limiting can key on a JWT claim (e.g. sub) as its counting characteristic

Cloudflare's current recommendation: use WAF Custom Rules to act on JWT results for new policies (supports zone-wide or endpoint-scoped policies, and can combine JWT results with other signals like Attack Score) — legacy "token validation rules" still work but aren't the forward path.

// Reference a custom claim in a rule
lookup_json_string(http.request.jwt.claims["<TOKEN_CONFIG_ID>"][0], "claim_name")

Special cases worth knowing: validating two JWTs from different identity providers on one request requires two separate token configurations, selecting "Validate all configurations." Migrating between identity providers similarly needs two configs and two validation rules, so you can flip actions independently as the migration progresses.

How to actually set up a token configuration

1. Go to the Security → Settings page.
2. Filter by API abuse.
3. On Token configurations, select Configure tokens.
4. Name the configuration.
5. Choose where Cloudflare should look for the JWT on incoming requests — a specific header or cookie, and its name.
6. Paste in your issuer's verification keys (JWKS) — asymmetric public keys, or a symmetric HMAC credential. If you don't know where to get these, that's an identity-admin question on the customer's side, not something to guess at.

Then act on the result with a WAF Custom Rule (Module 1 list, same Custom Rule flow as Module 3/4) referencing http.request.jwt.claims.

Module 8Decision framework — detection vs. mitigation, and what to actually block

Given Module 1's core point, here's the practical mapping: what's pure detection (needs a rule to act), and exactly what field/mechanism turns it into real enforcement.

Notice the pattern: anything with the word "Detection" or "Posture" or "Analytics" in its name is almost certainly observation-only. Anything named "Validation" or "Mitigation" is built to actually act. When in doubt on a call, default to assuming detection-only and confirm the enforcement path before promising a customer it blocks anything automatically.

What to actually block vs. allow vs. just log — real criteria, not "it depends"

Module 8's table above tells you the mechanism. This is the part that's actually missing from most API Shield conversations: once you've wired up the Custom Rule, what should it do? Unlike Bot Management's continuous 1-99 score, most API Shield signals are binary (matches the expected shape, or doesn't) — which makes people assume the answer is always "just Block it." It isn't, for exactly one reason: the false-positive cost of a legitimate client is a broken API integration for a real customer, not an annoying CAPTCHA.

Module 9Plans, positioning & competitive context

Unlike Bot Management's multi-tier structure (Free/Pro/Business/Enterprise), API Shield doesn't have a comparable ladder.

GraphQL and gRPC

GraphQL malicious query protection is available to all API Shield customers (not a separate subscription) — it scans GraphQL traffic and blocks queries that could overload the origin, via three Custom Rule fields: cf.api_gateway.graphql.query_size (number of terminal fields/leaves requested, not byte size), cf.api_gateway.graphql.query_depth (nesting depth), and cf.api_gateway.graphql.parsed_successfully. Cloudflare's own documented example rule: query_size > 30 and query_depth > 7 and parsed_successfully → Block.

gRPC: Cloudflare can proxy and protect gRPC services with the same core controls (rate limiting, mTLS, etc.).

Why Cloudflare over point products (Salt, Noname, 42Crunch, Traceable, etc.)

1. Same edge as everything else — no separate inline component, no traffic mirroring to a third-party pipeline
2. Network-scale advantage — Cloudflare observes a huge share of global internet traffic, including API attack patterns no single-customer point product can ever see
3. One policy language — combine API-specific rules with WAF, bot score, and identity signals in the same Custom Rule
4. No agents, no SDKs, no traffic re-routing — if you're already proxied through Cloudflare, the data is already there
5. Built-in mTLS managed CA — most competitors require you to bring external PKI

Module 10Live demo & test commands

Real, tested curl commands against a live demo API (api.tarheel.us), each cross-linked to the module that explains why it works.

Schema Validation tests (Module 3)

// TEST 1 — Valid login → 200
curl -is -w "\nStatus: %{http_code}\n" \
  -X POST https://api.tarheel.us/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"hunter2"}'

// TEST 2 — Missing required field → 403 (blocked by schema, never reached the app)
curl -is -w "\nStatus: %{http_code}\n" \
  -X POST https://api.tarheel.us/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo"}'

// TEST 3 — Extra field / mass assignment attempt → 403
// Schema has additionalProperties: false — the "role" field alone triggers the reject
curl -is -w "\nStatus: %{http_code}\n" \
  -X POST https://api.tarheel.us/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"hunter2","role":"admin"}'

// TEST 4 — Wrong data type (SQLi payload in an integer field) → 403
// Caught because the shape is wrong, not because of a SQLi-specific rule
curl -is -w "\nStatus: %{http_code}\n" \
  -X POST https://api.tarheel.us/orders \
  -H "Content-Type: application/json" \
  -d '{"product_id":"DROP TABLE products;--","quantity":1}'

Rate Limiting / Volumetric Abuse tests (Module 4)

// TEST 5 — Credential stuffing → 429 after 5 tries
for i in {1..10}; do
  RESP=$(curl -sD - -o /dev/null -w "STATUS=%{http_code}" \
    -X POST https://api.tarheel.us/login \
    -H "Content-Type: application/json" \
    -d "{\"username\":\"victim\",\"password\":\"guess$i\"}")
  STATUS=$(echo "$RESP" | grep '^STATUS=' | cut -d= -f2)
  RAY=$(echo "$RESP" | grep -i '^cf-ray:' | awk '{print $2}' | tr -d '\r')
  echo "Attempt $i:  status=$STATUS  cf-ray=$RAY"
done

First 5 attempts return 401 (wrong password, from your origin — Cloudflare proxied them through). Sixth onward returns 429 from Cloudflare itself, before ever reaching the origin.

// TEST 6 — BOLA enumeration → 429 after 20 tries
for i in {1..30}; do
  RESP=$(curl -sD - -o /dev/null -w "STATUS=%{http_code}" \
    https://api.tarheel.us/users/$i)
  STATUS=$(echo "$RESP" | grep '^STATUS=' | cut -d= -f2)
  RAY=$(echo "$RESP" | grep -i '^cf-ray:' | awk '{print $2}' | tr -d '\r')
  echo "User $i:  status=$STATUS  cf-ray=$RAY"
done

Twenty requests succeed, then 429 — an attacker can't enumerate every user ID. This is the live version of exactly the enumeration signal BOLA vulnerability detection looks for (Module 5), just demonstrated as a hard rate-limit block rather than a passive detection label.

GraphQL malicious query protection, live (Module 9)

// Benign → 200
curl -X POST https://cf-demo-app.dustinburke23nc.workers.dev/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ user(id: \"42\") { id name } }"}'

// Deeply-nested → 403 (simulated block, matches query_depth > 7)
curl -X POST https://cf-demo-app.dustinburke23nc.workers.dev/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ a { b { c { d { e { f { g { h { i { j } } } } } } } } } }"}'

This endpoint is on workers.dev — there's no real Cloudflare WAF in front of it, so it simulates the block response shape for safe scripting/screenshots. For a demo with a real edge decision and real Security Analytics event, the identical logic runs behind an actual Enterprise zone with API Shield enabled at graphql.tarheel.us/graphql — use that one when you want to show the WAF block itself, not just the response shape.

Module 11Rapid-fire Q&A

Self-testQuiz

Click a question to reveal the answer. No peeking before you commit to one.