Skip to content

Edge Side Code deprecation

Edge Side Code (ESC) is a customization option used by several Enterprise customers that allows for more configurability of Cloudflare’s global network features. This code can alter the behavior of Cloudflare’s CDN, enabling logic for specific customer use cases. Currently, a few customers have ESC in place to perform special operations such as advanced header manipulation, host header switching.

Edge Side Code is now deprecated. All configurations currently done via ESC will be removed on 2025-01-01. If you are using ESC, you will need to configure other Cloudflare products to replace your current ESC configuration before this date.

Will this deprecation affect my account?

If your account is currently using ESC, your account team will contact you so that you can discuss the migration from ESC to other existing Cloudflare products.

Which Cloudflare products should I use instead?

The following table contains recommendations for different use cases of ESC:

Use caseDescriptionAlternative
Redirect to URLNavigate visitors to a different URL without sending the request to the origin server.Use Single Redirects or Bulk Redirects.
Rewrite SNIOverride the hostname used for TLS SNI when connecting to the origin server.Use Origin Rules to override the Server Name Indication (SNI) value of a request.
Cloudflare for SaaS customers can perform SNI rewrites via custom hostnames.
Resolve overrideOverride the resolved hostname used to reach the origin server.Use Origin Rules to override the resolved hostname of incoming requests.
Rewrite URIRequest a different URL from the origin server while displaying the original request URL in the visitor’s browser.Use Transform Rules to rewrite URLs.
Set/clear request headersSet (or clear) HTTP headers sent to the origin server.Use Transform Rules to modify request headers.
Feature exceptionsExclude specific requests from one or more Cloudflare security products.Use Configuration Rules.
Send custom error responseAbort the current request, returning a specific response body and/or HTTP status code to the client.Use Custom Error Responses to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers).
Set/add/remove response headersUpdate, add, or remove headers from the response returned by the origin server.Use Transform Rules to modify response headers.
Status redirectAfter receiving a response from the origin, conditionally send a redirect back to the client if the origin response code matches a key in the supplied table.Use Cloudflare Workers. Refer to the Modify response example for a similar use case.
Add cookies to responseSet cookies in the response sent to the client.Use Transform Rules to modify response headers (which includes setting cookies).

For more complex use cases, consider using Cloudflare Workers.

Can I disable ESC right now to understand the deprecation impact?

Yes, you can disable ESC via API. The API allows you to:

  • Understand the impact of disabling ESC on your account or zone.
  • Test your alternative configuration with other Cloudflare products (and with ESC disabled) before the sunset date.

What kind of tests can I run?

The available API operations allow you to do the following:

  • Disable ESC for individual requests: Any test requests containing a cookie with a specific secret will be processed with ESC disabled.
  • Disable/enable ESC for a specific zone: After disabling ESC for a zone, all incoming requests for the zone will have all ESC configurations disabled.
  • Disable/enable ESC for an entire account: After disabling ESC for an account, all incoming requests for any zone in the account will have all ESC configurations disabled.

Cloudflare recommends that you start doing tests using individual HTTP requests, to make sure the triggered rules and the response you get match your expectations.

Start by configuring a secret and including it in a request cookie to disable ESC for specific requests.

If these tests are successful, disable ESC for the entire zone. Perform some additional tests to make sure that your configuration with ESC disabled performs as intended. If you detect any issues, re-enable ESC for the zone.

If you wish, you can also disable ESC for an entire account. This will affect all incoming requests for all zones in your account.


Disabling ESC via API

The available API operations allow you to disable ESC for an account/zone and re-enable ESC in a few seconds and in self-service mode.

You can also configure a secret to perform per-request tests without changing the ESC status (disabled or enabled) for account or zone. Use this feature to check if the appropriate rules are being triggered and if the request/response matches your expectations.

To disable/enable ESC for individual requests, do the following:

  1. Create a secret (up to 100 characters) using the Create ESC secret for a zone or Create ESC secret for an account operation.

  2. Include the secret in your test requests using a cookie named disable_esc. This will only disable ESC for these test requests addressed at your zone or account, according to the endpoint scope you used in the previous step (zone or account). The following example HTTP request header defines a cookie for disabling ESC for the current request:

    Cookie: disable_esc=<SECRET>

To change the ESC status for a zone, use the following operations:

To change the ESC status for an account, use the following operations:

API operations

NameHTTP verbEndpoint
Get ESC secret or status for a zoneGET/zones/{zone_id}/disable_esc
Create ESC secret for a zonePOST/zones/{zone_id}/disable_esc
Disable ESC for a zonePOST/zones/{zone_id}/disable_esc
Re-enable ESC for a zoneDELETE/zones/{zone_id}/disable_esc
Get ESC secret or status for an accountGET/accounts/{account_id}/disable_esc
Create ESC secret for an accountPOST/accounts/{account_id}/disable_esc
Disable ESC for an accountPOST/accounts/{account_id}/disable_esc
Re-enable ESC for an accountDELETE/accounts/{account_id}/disable_esc

To invoke an API operation, append the operation endpoint to the Cloudflare API base URL:

https://api.cloudflare.com/client/v4

API examples

Get ESC status for a zone

This example obtains the current status of the Disable ESC setting for the specified zone. The same endpoint will return the currently configured ESC secret for the zone, if configured.

Terminal window
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"

The following example response states that ESC is disabled for the entire {zone_id} zone:

{"always": true}

The following example response includes the previously configured secret for the zone using the Create ESC secret for a zone operation:

{"with_secret": "<SECRET>"}

Create ESC secret for a zone

This POST request example configures an ESC secret for disabling ESC in specific requests for the {zone_id} zone, setting the secret to MySecretString321#.

Terminal window
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "with_secret": "MySecretString321#" }'

The maximum secret length is 100 characters.

To use the secret, include a cookie named disable_esc with the secret value in any requests for which you want to have ESC disabled:

Terminal window
curl "https://example.com/company_app" \
--header "Cookie: disable_esc=MySecretString321#"

This will only disable ESC for the request that includes the cookie.

Disable ESC for a zone

This POST request example disables ESC for all incoming requests of {zone_id} zone.

Terminal window
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "always": true }'

Re-enable ESC for a zone

This example re-enables ESC for the {zone_id} zone.

Terminal window
curl --request DELETE \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"

Get ESC status for an account

This example obtains the current status of Disable ESC setting for the specified account. The same endpoint will return the currently configured ESC secret for the account, if configured.

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"

The following example response states that ESC is disabled for the entire {account_id} account:

{ "always": true }

The following example response includes the previously configured secret for the account using the Create ESC secret for an account operation:

{ "with_secret": "<SECRET>" }

Create ESC secret for an account

This example configures an ESC secret for disabling ESC in specific requests for the {account_id} account, setting the secret to MySecretString321#.

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "with_secret": "MySecretString321#" }'

The maximum secret length is 100 characters.

To use the secret, include a cookie named disable_esc with the secret value in any requests for which you want to have ESC disabled:

Terminal window
curl "https://example.com/company_app" \
--header "Cookie: disable_esc=MySecretString321#"

This will only disable ESC for the request that includes the cookie.

Disable ESC for an account

This POST request example disables ESC for all incoming requests of {account_id} account.

Terminal window
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "always": true }'

Re-enable ESC for an account

This example re-enables ESC for the {account_id} account.

Terminal window
curl --request DELETE \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"

Final remarks

Some configurations currently done using ESC will not be directly available in any other Cloudflare product. In this rare situation, Cloudflare will discontinue the custom behavior currently obtained through ESC and work with you to help you understand alternative solutions for your use cases.