10 · Cache keys and cache security
Decide which query parameters, headers, cookies, and user dimensions truly change a response to prevent fragmentation, cross-user reuse, and web cache poisoning.
Edited and verified by Orange Book Editorial Team ·
Outcome
Only dimensions that genuinely change a public response participate in its cache key. Proven tracking parameters can be consolidated, identity and private variants cannot cross-read because of a missing dimension, and invalidation covers every real cache variant.
The cache key is an object's identity
flowchart LR
A[Request URL + selected inputs] --> B[Build Cache Key]
B --> C{Same key?}
C -- Yes --> D[May reuse one cached object]
C -- No --> E[Store or read a separate variant]Removing a dimension increases reuse by consolidating requests. Adding a dimension isolates responses but can create objects that each hit only once. The goal is not the shortest or longest key: requests with identical responses share a key; requests with different responses never do.
Cloudflare considers the query string by default, and the Origin request header is in the default key for CORS boundaries. Ignore Query String makes file.jpg?a=1 and file.jpg?a=2 share an object. That is safe only when the origin returns the same public response for both.
Use an input-output matrix
| Input dimension | Potentially safe to ignore | Must isolate or bypass |
|---|---|---|
| Query parameter | Tracking-only utm_* after proving no output change | tenant, user, token, size/format, language, version |
| Cookie | Analytics cookie that does not change a public page | Session, permission, cart, experiment, draft preview |
| Request header | Not read or reflected by the application | Authorization, tenant, language, device, custom variant |
| Hostname | Same content and authorization boundary | Multi-tenant custom domains, distinct brands or permissions |
| Country/device/language | Origin always returns identical bytes | Actual regulatory, template, or language variants |
Do not place secrets in cacheable URLs
A query parameter participating in the cache key is not authorization. Tokens, signatures, user IDs, and private-object URLs can leak through logs, analytics, and browser history. Bypass private responses first and enforce identity plus object permissions in the application.
Three classes of security failure
Missing dimension: cross-variant reuse
If an application varies by X-Tenant but the header is absent from the key, tenants can share an object. On a plan that cannot express the full custom key, split by Hostname/path or bypass rather than pretending the responses are identical.
Unkeyed input reflection: cache poisoning
If the origin writes an arbitrary request header into HTML while that header is absent from the key, an attacker can seed a harmful version for normal visitors. Cache only responses that are genuinely static and independent of untrusted inputs. Never reflect an unvalidated header into content, redirects, or asset URLs.
A GET body changes the response
Cloudflare does not include a GET request body in the cache key. If an application lets that body alter output, one key can represent multiple responses. Correct the request semantics or bypass the route.
Plan and feature boundary
| Capability | Current availability |
|---|---|
| Cache Deception Armor | Free / Pro / Business / Enterprise |
| Ignore Query String, Sort Query String, Cache by Device Type | All plans |
| Custom Query, Header, Cookie, Host, User dimensions | Enterprise |
Cache Deception Armor reduces the risk of attackers disguising dynamic paths as static file extensions. It does not replace route classification, correct response headers, and identity bypasses.
Safe change workflow
Collect paired requests
For each candidate dimension, prepare two requests that change only that input. Save status, headers, body hash, and permission context. Test two utm_source values, two languages, and two accounts independently.
Prove whether output is identical
Consolidate only when status, body, redirect, CORS, and cookie behavior all agree. Preserve the default key or bypass when evidence is missing.
Change a test hostname
Modify one dimension at a time and enable Cache Deception Armor. When using URL Normalization, also evaluate Normalize URLs to origin as Cloudflare recommends so the normalized cache URL and origin URL cannot diverge.
Verify with Trace and cross-clients
Use Cloudflare Trace to inspect the actual Cache Key parameters, then request variants as anonymous, account A, and account B. Success means identical output consolidates and different output remains isolated, not merely a higher hit ratio.
Couple invalidation design
When a custom key includes a Header, Cookie, device, country, or language, a URL purge may need the same values that formed the key. Prove that the release system can invalidate every variant before rolling it into production.
Next, connect the cache key to the release invalidation workflow.
Primary sources
Did this page help you complete your goal?
Beta feedback is generated in this browser and is never uploaded automatically.
09 · Cache patterns for CMS, SaaS, and AI-built applications
Partition CMS, SaaS, image, and PDF tools by visibility, identity, method, and lifecycle so dynamic pages from AI-generated code never enter cache accidentally.
11 · Targeted purge and release workflow
Combine versioned URLs, URL/Tag/Prefix/Hostname purge, and verifiable rollback so fresh content ships without creating a zone-wide origin surge.