Cache keys

A Cache Key is an identifier that Cloudflare uses for a file in our cache, and the Cache Key Template defines the identifier for a given HTTP request.

A default cache key includes:

1. Full URL:
   • scheme - could be HTTP or HTTPS.
   • host - for example, www.cloudflare.com
   • URI with query string - for example, /logo.jpg
2. Origin header sent by client (for CORS support).
3. x-http-method-override, x-http-method, and x-method-override headers.
4. x-forwarded-host, x-host, x-forwarded-scheme (unless http or https), x-original-url, x-rewrite-url, and forwarded headers.

Create custom cache keys

Custom cache keys let you precisely set the cacheability setting for any resource. They provide the benefit of more control, though they may reduce your cache hit rate and result in cache sharding:

1. Log in to your Cloudflare dashboard ↗, and select your account and domain.
2. Go to Caching > Cache Rules.
3. Select Create rule.
4. Under When incoming requests match, define the rule expression.
5. Under Then, in the Cache eligibility section, select Eligible for cache.
6. Add the Cache Key setting to the rule and select the appropriate Query String setting.
7. You can also select settings for Headers, Cookie, Host, and User.
8. To save and deploy your rule, select Deploy. If you are not ready to deploy your rule, select Save as Draft.

Cache Key Template

There are a couple of common reasons to change the Cache Key Template. You might change the Cache Key Template to:

• Fragment the cache so one URL is stored in multiple files. For example, to store different files based on a specific query string in the URL.
• Consolidate the cache so different HTTP requests are stored in the same file. For example, to remove the Origin header added to Cloudflare Cache Keys by default.

Impact of SSL settings on Cache behavior

The $scheme refers to the protocol (HTTP or HTTPS) sent to your origin web server, not the protocol received from the visitor. Therefore, setting the Cloudflare SSL option influences caching decisions. For example, when using Flexible SSL, Cloudflare only attempts to connect to your origin web server via HTTP. This means that 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.

It is important to understand how SSL setting changes affect the cache:

• Switching from Off to Full, Full (strict), or Strict will change the origin scheme from HTTP to HTTPS. This results in a cache bust, meaning the cached content becomes invalid and needs to be re-fetched from the origin server.

• Transitioning from Flexible to Full, Full (strict), or Strict changes the origin scheme from HTTP to HTTPS, causing a cache bust.

• Downgrading from Full, Full (strict), or Strict to Flexible or Off changes the origin scheme from HTTPS to HTTP, resulting in a cache bust.

This behavior is important to consider when adjusting SSL settings, as any change in the origin scheme (HTTP to HTTPS or vice versa) triggers a cache reset.

Cache Level: Ignore Query String

A Cache Level of Ignore Query String creates a Cache Key that includes all the elements in the default cache key, except for the query string in the URI that is no longer included. For instance, a request for http://example.com/file.jpg?something=123 and a request for http://example.com/file.jpg?something=789 will have the same cache key, in this case.

Cache Key Settings

The following fields control the Cache Key Template.

Query String

The query string controls which URL query string parameters go into the Cache Key. You can include specific query string parameters or exclude them using the respective fields. When you include a query string parameter, the value of the query string parameter is used in the Cache Key.

Example

If you include the query string foo in a URL like https://www.example.com/?foo=bar, then bar appears in the Cache Key. Exactly one of include or exclude is expected.

Usage notes

• To include all query string parameters (the default behavior), use include: ”*”
• To ignore query strings, use exclude: ”*”
• To include most query string parameters but exclude a few, use the exclude field which assumes the other query string parameters are included.

Headers

Headers control which headers go into the Cache Key. Similar to Query String, you can include specific headers or exclude default headers.

When you include a header, the header value is included in the Cache Key. For example, if an HTTP request contains an HTTP header like X-Auth-API-key: 12345, and you include the X-Auth-API-Key header in your Cache Key Template, then 12345 appears in the Cache Key.

In the Check if header contains section, you can add header names and their values to the cache key. For custom headers, values are optional, but for the following restricted headers, you must include one to three specific values:

• accept
• accept-charset
• accept-encoding
• accept-datetime
• accept-language
• referer
• user-agent

To check for the presence of a header without including its actual value, use the Check presence of option.

Currently, you can only exclude the Origin header. The Origin header is always included unless explicitly excluded. Including the Origin header ↗ in the Cache Key is important to enforce CORS ↗.

Additionally, you cannot include the following headers:

• Headers that re-implement cache or proxy features
  • connection
  • content-length
  • cache-control
  • if-match
  • if-modified-since
  • if-none-match
  • if-unmodified-since
  • range
  • upgrade
• Headers that are covered by other Cache Key features
  • cookie
  • host
• Headers that are specific to Cloudflare and prefixed with cf-, for example, cf-ray
• Headers that are already included in the custom Cache Key template, for example, origin

Host

Host determines which host header to include in the Cache Key.

• If resolved: false, Cloudflare includes the Host header in the HTTP request sent to the origin.
• If resolved: true, Cloudflare includes the Host header that was resolved to get the origin IP for the request. In this scenario, the Host header may be different from the header actually sent if the Cloudflare Resolve Override feature is used.

Cookie

Like query_string or header, cookie controls which cookies appear in the Cache Key. You can either include the cookie value or check for the presence of a particular cookie.

Usage notes

You cannot include cookies specific to Cloudflare. Cloudflare cookies are prefixed with __cf, for example, __cflb

User features

User feature fields add features about the end-user (client) into the Cache Key.

• device_type classifies a request as mobile, desktop, or tablet based on the User Agent
• geo includes the client’s country, derived from the IP address
• lang includes the first language code contained in the Accept-Language header sent by the client

Availability

Cache keys options availability varies according to your plan.

	Free	Pro	Business	Enterprise
Cache deception armor	Yes	Yes	Yes	Yes
Cache by device type	Yes	Yes	Yes	Yes
Ignore query string	Yes	Yes	Yes	Yes
Sort query string	Yes	Yes	Yes	Yes
Query string	No	No	No	Yes
Headers	No	No	No	Yes
Cookie	No	No	No	Yes
Host	No	No	No	Yes
User features	No	No	No	Yes

Limitations

The Prefetch feature is not compatible with the custom cache keys. With Cache Rules, the custom cache key is used to cache all assets. However, Prefetch always uses the default cache key. This results in a key mismatch.