Using Cache Keys

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}

$scheme is the protocol (HTTP or HTTPS) sent to your origin web server and not the protocol received from the visitor. Therefore, setting the Cloudflare SSL option influences caching decisions. For instance, Cloudflare only attempts to connect to your origin web server via HTTP when Flexible SSL is utilized. Thus, Cloudflare serves the same cached resource for visitor requests via either HTTP or HTTPS since Flexible SSL instructs Cloudflare to connect to an origin solely over HTTP.

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 KeysCache 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"}}]}'


Related resources

Not finding what you need?

95% of questions can be answered using the search tool. This is the quickest way to get a response.

Powered by Zendesk