Learn how Cache Keys for Enterprise plans control how resources are served from Cloudflare’s CDN cache.
Overview
Cache Keys define what information in a visitor's HTTP request matches resources in your Cloudflare CDN cache. Only Cloudflare Enterprise plans are allowed Cache Keys.
Cloudflare’s URL-based caching delivers resources to your visitor when the requested URL matches a Cache Key configured by a Cloudflare Page Rule. Use Cache Keys to:
- customize Cloudflare’s cache responses when the origin web server varies responses other than by URL. For example, serve a different image file from cache based on your visitor’s device (mobile, tablet, or desktop).
- increase the cache-hit rate for requests that are normally cached separately. For example, for requests containing a unique session ID, such as image.jpg?session=uniquesessionID, Cache Keys serve one cached resource regardless of unique session ID.
For all Cache Levels except Ignore Query Strings, Cloudflare’s default Cache Key is:
${header:origin}::${scheme}://${host_header}${uri}
For a typical request for a resource such as https://www.example.com/<asset>, Cloudflare generates a simple Cache Key:
::https://www.example.com/<asset>
For cross-origin requests, such as one from anotherdomain.com to example.com, the Origin HTTP request header results in a Cache Key with the ${header:origin} token populated:
anotherdomain.com::https://www.example.com/something
A Cache Level of Ignore Query String creates the following Cache Key:
${header:origin}::${scheme}://${host_header}${uri_iqs}
${uri_iqs} is replaced with the request path excluding the query string, so a request for http://example.com/file.jpg?something=123 creates the following Cache Key:
::http://example.com/file.jpg
Create a Cache Key
Contact your Cloudflare Account Team to enable or modify Cache Keys. Cache Keys are only applied via Cloudflare Page Rules.
The modifiable portions of a Cache Key include:
- Scheme - HTTP or HTTPS requests
- Geo - the two-letter country code for a visitor’s country of origin
- Language - As specified in the Accept-Language header from the browser (trimmed to the first language)
- Cookie test - whether a browser cookie is provided (indicated by a 0 or 1)
- Cookie content - the full value of the cookie (available only under certain circumstances)
- Header test - match found in the browser’s request header (indicated by a 0 or 1)
- Header content - the full value of the specified header
- Device type - a header value indicating the user’s device (mobile, tablet, or desktop)
Purge a Cache Key resource
Purge resources that use Cache Keys via the Cloudflare API.
Purge by device type
For a Cache Key based on device type, purge the asset by passing the CF-Device-Type header with the API purge request (valid headers include mobile, desktop, and tablet):
Here is an example API request to purge all mobile assets on the root web page:
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_tag}/purge_cache" -H "X-Auth-Email: user@example.com" -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" -H "Content-Type: application/json" --data '{"files":[{"url":"http://my.website.com/","headers":{"CF-Device-Type":"mobile"}}]}'Purge by geo
Purge resources for a location-based Cache Key by specifying the two-letter country code (Spain is used in the example below):
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_tag}/purge_cache" -H "X-Auth-Email: user@example.com" -H "X-Auth-Key: c2547eb745079dac9320b638f5e225cf483cc5cfdda41" -H "Content-Type: application/json" --data '{"files":[{"url":"http://my.website.com/", "headers":{"Cf-Ipcountry":"ES"}}]}'