As the lead for a public API on Cloudflare whose clients send an API key header, some from shared egress IPs, how do you decide what its rate limits are keyed on?
answer
- layers, not one key
- the client controls header values
- a ceiling per address
- plan decides the characteristics
- exact quotas live elsewhere
basics
~20 sLayer the limits: a high per-IP ceiling that shared egress addresses can live with, a per-customer limit keyed on a validated key or claim, and a failed-authentication limit. Plan, precision and who owns the thresholds decide which layer holds which key.
solid answer
~40 sI treat IP as the coarse layer, because NAT gateways and proxies put many customers behind one address, so its ceiling sits above the busiest honest address. The customer layer keys on the API key, but a raw header is client-supplied and each invented key gets a fresh counter, so I pair it with that IP ceiling and a per-IP limit on `401` answers, or key on a verified JWT claim. Header characteristics need Enterprise with Advanced Rate Limiting; on Business, the per-customer limit moves into a Worker's rate limiting binding keyed on the customer ID, behind an edge rule. Requests without the header share one counter, so they get their own rule. Billable quotas stay in the application, since edge counters are approximate. Product owns published limits, security owns abuse ceilings.
go deeper
Know that API clients often share IP addresses, so an API key is usually a better per-customer key than an IP.
Explain which characteristics each plan allows, why missing headers form their own counter, and how the Workers binding keys on any string.
Show how invented keys defeat a header-only rule and how an IP ceiling, failure counting or a verified claim closes that gap.
Own the layering: which key lives at which layer, what each plan costs, where exact quotas are counted, and who may change each threshold.
## The decision A public API whose clients authenticate with an API key header looks easy to rate limit: count per key. In practice the lead has to decide what each limit is keyed on, at which layer it runs, and which plan it needs, knowing that many legitimate clients share addresses (cloud NAT gateways, corporate proxies, carrier networks) and that some traffic is abusive. There is no single right key; there is a set of layers, each covering a failure of the others. ## What each key gives you | Key | Where | Strength | Failure mode | |---|---|---|---| | IP | Rate limiting rule, every plan | Needs no client cooperation | Punishes everyone behind a shared address | | IP with NAT support | Rule, Business and up | Separates visitors behind one address | Cookie-less API clients collapse into one counter | | Header value of the key | Rule, Enterprise with Advanced Rate Limiting | Counts per customer before the origin | Counts invented keys too | | JWT claim | Rule, with an API Shield token validation configuration | Counts per verified subject | Needs API Shield and JWT-shaped keys | | Any string from code | Workers rate limiting binding | Per customer, per tier, per route | Runs only after the Worker is invoked; 10 or 60 s periods | ## Keying on a value the client controls A header is client-supplied. A rule keyed only on `http.request.headers["x-api-key"]` gives an abuser a fresh counter for every value they invent, so a run of random keys never trips it. Cloudflare's advice for cookie characteristics applies here too: validate the value at the origin before doing expensive work, and don't trust it just because the edge counted it. In practice: - Put a **per-IP ceiling** beside the per-key rule, set well above the busiest honest shared address, so invented keys from one address are still capped. - Count **authentication failures** (`401`) per IP with a counting expression, so key guessing is limited by its own failures. - Where tokens are JWTs, key on a **verified claim** instead of a raw header, or validate the key in a Worker and call the binding with the customer ID. Requests that lack the header altogether share **one** counter of their own. Decide whether no-key traffic gets its own stricter rule, and filter the keyed rule with `len(http.request.headers["x-api-key"]) > 0` so the two do not mix. In the API, the header name must be lowercase. ## Choosing the layer 1. **Edge rules** stop floods before they cost origin or Worker time, and their Block action can return a JSON `429` that clients can program against. They are limited to the plan's characteristics and to per-data-center counting. 2. The **Workers binding** keys on anything the code can compute, such as a customer tier looked up from the key, and different tiers can use different bindings with their own namespaces. Each limited call is still a Worker invocation, so it sits behind an edge rule, not instead of one. 3. **Contractual quotas** (a monthly allowance a customer pays for) need an exact count, which neither edge counters nor the binding provide; they belong in the application's own accounting, for example a strongly consistent counter per customer. ## Plan cost and ownership - Header, cookie and query characteristics need **Enterprise with Advanced Rate Limiting**, and a JWT-claim key also needs an API Shield token validation configuration; Business stops at IP and IP with NAT support plus a counting expression. If the budget is Business, the per-customer layer moves into a Worker. - Partners on fixed addresses can be excluded with an IP list in the expression (`not ip.src in $partner_ips`); a rule that references a list must keep **Also apply rate limiting to cached assets** on. - Decide **who owns thresholds**: product sets the published per-tier limits, security owns the abuse ceilings, and changes start in **Log** (Enterprise) or with a loose threshold, then tighten from Security Events. - Publish the limits and the `429` body so customers can build back-off. An undocumented edge limit becomes a support ticket the first time a customer's batch job hits it. ## What a good answer weighs - Shared egress makes IP the coarse layer, never the customer layer. - A per-key layer is only as good as the key's validation. - Exact counts exist only in the application's own accounting; edge rules and the binding are both approximate, and a flood is cheapest to stop at the edge. - The plan decides which layer can hold which key.
- Why does a Cloudflare rate limiting rule keyed only on an API key header fail against an abuser who rotates keys?Every distinct header value gets its own counter, so a client sending a new invented key on each request never accumulates enough requests on any counter to trip the rule. Back the per-key rule with a per-IP ceiling and a limit on authentication failures, or key on a value Cloudflare has verified, such as a JWT claim from API Shield token validation.
- What happens to requests that do not send the header a Cloudflare rate limiting rule is keyed on?They are not skipped: the rule still applies, and all requests missing the header share one counter, distinct from the counter for an empty value. Unless that is intended, add `len(http.request.headers["x-api-key"]) > 0` to the counting expression and give unauthenticated traffic its own rule.
- Keying on the API key header alone stops abusers, since every request carries one.
- A Business zone can key a rate limiting rule on any request header.
- Requests missing the keyed header are skipped by the rule.
- Edge rate limits are exact enough to enforce a customer's monthly billed quota.
- The Workers binding can replace edge rules, since limited requests never invoke the Worker.
Assumes Cloudflare as of 2026-10-10, where header and cookie characteristics need Enterprise with Advanced Rate Limiting and Business offers IP and IP with NAT support.