A cache key is a unique string that lets Akamai edge servers look for your content when requests hit them. It’s made up of a few different pieces (like origin hostname, path, and filename).

By default, cache key doesn’t include request headers value, but you might want to cache and serve different content based upon the value of a particular request header.

For example, serving a WebP image if the browser supports WebP format by specifying image/WebP in the Accept header value. Here are a couple of ways to modify cache key in Akamai.

Using Cache ID modification module

This method is the easiest way to modify cache key. It takes the cache control options for setting the cache key beyond just path, filename, and query parameters by adding header or cookie values to the mix.

However, this is only available with the inclusion of Advanced Cache Optimization module.

Use Variables and Modify outgoing request path behavior

Suppose you want to serve a WebP image on a particular request if Accept header value has image/WebP in it.

Modify Cache Key In Akamai Based Upon Request Header Value
Accept header value has image/WebP in Chrome

Follow the below steps to modify cache key without using Cache ID modification

1. Create a property variable, e.g. IS_WEBP, and assign it an initial value false

Modify Cache Key In Akamai
Create a property variable IS_WEBP with initial value: false

You can learn more about property variables from here. But, for now, the above screenshot contains enough information to create a variable IS_WEBP with an initial value false.

2. Update value of IS_WEBP variable based upon Accept header value.

Modify Cache Key In Akamai
Update IS_WEBP value based upon Accept header value

3. Make sure that you have checked “Allow wildcards in value” under additional settings of match criteria.

Allow wildcards in value

Since the value of Accept header can be:

image/webp,image/apng,image/*,*/*;q=0.8, so we match on *image/webp*.

By default, wildcards are not allowed and matched, so remember to check this field.

4. Modify outgoing request path to include this variable value

Modify outgoing request path to include IS_WEBP value

How to check if cache is being modified based on different Accept header values?

We can easily see the value of various debug headers that Akamai sets for a request. You can use Akamai debug headers for this.

Here's an example request on https://www.91-img.com/imageoptimize/uploads/59e47c2d4b16d/images.jpeg

In Chrome, notice that value of X-True-Cache-Key contains $$IS_WEBP=true$$.

Variable value included in cache key

Similarly, if you issue the same request in FireFox, you should see $$IS_WEBP=false$$ in the cache key field.

Hence, we have successfully modified the cache key based upon the value of Accept request header. And now, Akamai will serve and cache different copies at the same URL.

However, this method poses an entirely new problem by prepending $$IS_WEBP=true|false$$ in the path.

So, for example, if your original image is at the path below.


If Akamai receives a request for this image from Chrome, then Akamai will hit your origin server www.example.cow at the below endpoint


You need to ignore everything including $$…$$. You can easily do that with Varnish like this:

if (req.url ~ "\$\$IS_WEBP=") {
        set req.url = regsub( req.url, "/\$\$IS_WEBP=true\$\$/", "/");
        set req.url = regsub( req.url, "/\$\$IS_WEBP=false\$\$/", "/");

Reach out to us at developer@imagekit.io if you have any questions or suggestions.