Skip to content
Cloudflare API
Start here
API Reference
Zero Trust
Gateway
Configurations

Patch Zero Trust account configuration

zero_trust.gateway.configurations.edit(ConfigurationEditParams**kwargs) -> ConfigurationEditResponse
PATCH/accounts/{account_id}/gateway/configuration

Update (PATCH) a single subcollection of settings such as antivirus, tls_decrypt, activity_log, block_page, browser_isolation, fips, body_scanning, or certificate without updating the entire configuration object. This endpoint returns an error if any settings collection lacks proper configuration.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
ParametersExpand Collapse
account_id: str
settings: Optional[GatewayConfigurationSettingsParam]

Specify account settings.

activity_log: Optional[ActivityLogSettings]

Specify activity log settings.

enabled: Optional[bool]

Specify whether to log activity.

antivirus: Optional[AntiVirusSettings]

Specify anti-virus settings.

enabled_download_phase: Optional[bool]

Specify whether to enable anti-virus scanning on downloads.

enabled_upload_phase: Optional[bool]

Specify whether to enable anti-virus scanning on uploads.

fail_closed: Optional[bool]

Specify whether to block requests for unscannable files.

notification_settings: Optional[NotificationSettings]

Configure the message the user’s device shows during an antivirus scan.

enabled: Optional[bool]

Specify whether to enable notifications.

include_context: Optional[bool]

Specify whether to include context information as query parameters.

msg: Optional[str]

Specify the message to show in the notification.

support_url: Optional[str]

Specify a URL that directs users to more information. If unset, the notification opens a block page.

block_page: Optional[BlockPageSettings]

Specify block page layout settings.

background_color: Optional[str]

Specify the block page background color in #rrggbb format when the mode is customized_block_page.

enabled: Optional[bool]

Specify whether to enable the custom block page.

footer_text: Optional[str]

Specify the block page footer text when the mode is customized_block_page.

header_text: Optional[str]

Specify the block page header text when the mode is customized_block_page.

include_context: Optional[bool]

Specify whether to append context to target_uri as query parameters. This applies only when the mode is redirect_uri.

logo_path: Optional[str]

Specify the full URL to the logo file when the mode is customized_block_page.

mailto_address: Optional[str]

Specify the admin email for users to contact when the mode is customized_block_page.

mailto_subject: Optional[str]

Specify the subject line for emails created from the block page when the mode is customized_block_page.

mode: Optional[Literal["", "customized_block_page", "redirect_uri"]]

Specify whether to redirect users to a Cloudflare-hosted block page or a customer-provided URI.

One of the following:
""
"customized_block_page"
"redirect_uri"
name: Optional[str]

Specify the block page title when the mode is customized_block_page.

read_only: Optional[bool]

Indicate that this setting was shared via the Orgs API and read only for the current account.

source_account: Optional[str]

Indicate the account tag of the account that shared this setting.

suppress_footer: Optional[bool]

Specify whether to suppress detailed information at the bottom of the block page when the mode is customized_block_page.

target_uri: Optional[str]

Specify the URI to redirect users to when the mode is redirect_uri.

formaturi
version: Optional[int]

Indicate the version number of the setting.

body_scanning: Optional[BodyScanningSettings]

Specify the DLP inspection mode.

inspection_mode: Optional[Literal["deep", "shallow"]]

Specify the inspection mode as either deep or shallow.

One of the following:
"deep"
"shallow"
browser_isolation: Optional[BrowserIsolationSettings]

Specify Clientless Browser Isolation settings.

non_identity_enabled: Optional[bool]

Specify whether to enable non-identity onramp support for Browser Isolation.

url_browser_isolation_enabled: Optional[bool]

Specify whether to enable Clientless Browser Isolation.

certificate: Optional[Certificate]

Specify certificate settings for Gateway TLS interception. If unset, the Cloudflare Root CA handles interception.

id: str

Specify the UUID of the certificate used for interception. Ensure the certificate is available at the edge(previously called ‘active’). A nil UUID directs Cloudflare to use the Root CA.

Deprecatedcustom_certificate: Optional[CustomCertificateSettings]

Specify custom certificate settings for BYO-PKI. This field is deprecated; use certificate instead.

enabled: Optional[bool]

Specify whether to enable a custom certificate authority for signing Gateway traffic.

id: Optional[str]

Specify the UUID of the certificate (ID from MTLS certificate store).

binding_status: Optional[str]

Indicate the internal certificate status.

updated_at: Optional[datetime]
formatdate-time
extended_email_matching: Optional[ExtendedEmailMatching]

Configures user email settings for firewall policies. When you enable this, the system standardizes email addresses in the identity portion of the rule to match extended email variants in firewall policies. When you disable this setting, the system matches email addresses exactly as you provide them. Enable this setting if your email uses . or + modifiers.

enabled: Optional[bool]

Specify whether to match all variants of user emails (with + or . modifiers) used as criteria in Firewall policies.

read_only: Optional[bool]

Indicate that this setting was shared via the Orgs API and read only for the current account.

source_account: Optional[str]

Indicate the account tag of the account that shared this setting.

version: Optional[int]

Indicate the version number of the setting.

fips: Optional[FipsSettings]

Specify FIPS settings.

tls: Optional[bool]

Enforce cipher suites and TLS versions compliant with FIPS 140-2.

host_selector: Optional[HostSelector]

Enable host selection in egress policies.

enabled: Optional[bool]

Specify whether to enable filtering via hosts for egress policies.

inspection: Optional[Inspection]

Define the proxy inspection mode.

mode: Optional[Literal["static", "dynamic"]]

Define the proxy inspection mode. 1. static: Gateway applies static inspection to HTTP on TCP(80). With TLS decryption on, Gateway inspects HTTPS traffic on TCP(443) and UDP(443). 2. dynamic: Gateway applies protocol detection to inspect HTTP and HTTPS traffic on any port. TLS decryption must remain on to inspect HTTPS traffic.

One of the following:
"static"
"dynamic"
protocol_detection: Optional[ProtocolDetection]

Specify whether to detect protocols from the initial bytes of client traffic.

enabled: Optional[bool]

Specify whether to detect protocols from the initial bytes of client traffic.

sandbox: Optional[Sandbox]

Specify whether to enable the sandbox.

enabled: Optional[bool]

Specify whether to enable the sandbox.

fallback_action: Optional[Literal["allow", "block"]]

Specify the action to take when the system cannot scan the file.

One of the following:
"allow"
"block"
tls_decrypt: Optional[TLSSettings]

Specify whether to inspect encrypted HTTP traffic.

enabled: Optional[bool]

Specify whether to inspect encrypted HTTP traffic.

ReturnsExpand Collapse
class ConfigurationEditResponse: …

Specify account settings.

created_at: Optional[datetime]
formatdate-time
settings: Optional[GatewayConfigurationSettings]

Specify account settings.

activity_log: Optional[ActivityLogSettings]

Specify activity log settings.

enabled: Optional[bool]

Specify whether to log activity.

antivirus: Optional[AntiVirusSettings]

Specify anti-virus settings.

enabled_download_phase: Optional[bool]

Specify whether to enable anti-virus scanning on downloads.

enabled_upload_phase: Optional[bool]

Specify whether to enable anti-virus scanning on uploads.

fail_closed: Optional[bool]

Specify whether to block requests for unscannable files.

notification_settings: Optional[NotificationSettings]

Configure the message the user’s device shows during an antivirus scan.

enabled: Optional[bool]

Specify whether to enable notifications.

include_context: Optional[bool]

Specify whether to include context information as query parameters.

msg: Optional[str]

Specify the message to show in the notification.

support_url: Optional[str]

Specify a URL that directs users to more information. If unset, the notification opens a block page.

block_page: Optional[BlockPageSettings]

Specify block page layout settings.

background_color: Optional[str]

Specify the block page background color in #rrggbb format when the mode is customized_block_page.

enabled: Optional[bool]

Specify whether to enable the custom block page.

footer_text: Optional[str]

Specify the block page footer text when the mode is customized_block_page.

header_text: Optional[str]

Specify the block page header text when the mode is customized_block_page.

include_context: Optional[bool]

Specify whether to append context to target_uri as query parameters. This applies only when the mode is redirect_uri.

logo_path: Optional[str]

Specify the full URL to the logo file when the mode is customized_block_page.

mailto_address: Optional[str]

Specify the admin email for users to contact when the mode is customized_block_page.

mailto_subject: Optional[str]

Specify the subject line for emails created from the block page when the mode is customized_block_page.

mode: Optional[Literal["", "customized_block_page", "redirect_uri"]]

Specify whether to redirect users to a Cloudflare-hosted block page or a customer-provided URI.

One of the following:
""
"customized_block_page"
"redirect_uri"
name: Optional[str]

Specify the block page title when the mode is customized_block_page.

read_only: Optional[bool]

Indicate that this setting was shared via the Orgs API and read only for the current account.

source_account: Optional[str]

Indicate the account tag of the account that shared this setting.

suppress_footer: Optional[bool]

Specify whether to suppress detailed information at the bottom of the block page when the mode is customized_block_page.

target_uri: Optional[str]

Specify the URI to redirect users to when the mode is redirect_uri.

formaturi
version: Optional[int]

Indicate the version number of the setting.

body_scanning: Optional[BodyScanningSettings]

Specify the DLP inspection mode.

inspection_mode: Optional[Literal["deep", "shallow"]]

Specify the inspection mode as either deep or shallow.

One of the following:
"deep"
"shallow"
browser_isolation: Optional[BrowserIsolationSettings]

Specify Clientless Browser Isolation settings.

non_identity_enabled: Optional[bool]

Specify whether to enable non-identity onramp support for Browser Isolation.

url_browser_isolation_enabled: Optional[bool]

Specify whether to enable Clientless Browser Isolation.

certificate: Optional[Certificate]

Specify certificate settings for Gateway TLS interception. If unset, the Cloudflare Root CA handles interception.

id: str

Specify the UUID of the certificate used for interception. Ensure the certificate is available at the edge(previously called ‘active’). A nil UUID directs Cloudflare to use the Root CA.

Deprecatedcustom_certificate: Optional[CustomCertificateSettings]

Specify custom certificate settings for BYO-PKI. This field is deprecated; use certificate instead.

enabled: Optional[bool]

Specify whether to enable a custom certificate authority for signing Gateway traffic.

id: Optional[str]

Specify the UUID of the certificate (ID from MTLS certificate store).

binding_status: Optional[str]

Indicate the internal certificate status.

updated_at: Optional[datetime]
formatdate-time
extended_email_matching: Optional[ExtendedEmailMatching]

Configures user email settings for firewall policies. When you enable this, the system standardizes email addresses in the identity portion of the rule to match extended email variants in firewall policies. When you disable this setting, the system matches email addresses exactly as you provide them. Enable this setting if your email uses . or + modifiers.

enabled: Optional[bool]

Specify whether to match all variants of user emails (with + or . modifiers) used as criteria in Firewall policies.

read_only: Optional[bool]

Indicate that this setting was shared via the Orgs API and read only for the current account.

source_account: Optional[str]

Indicate the account tag of the account that shared this setting.

version: Optional[int]

Indicate the version number of the setting.

fips: Optional[FipsSettings]

Specify FIPS settings.

tls: Optional[bool]

Enforce cipher suites and TLS versions compliant with FIPS 140-2.

host_selector: Optional[HostSelector]

Enable host selection in egress policies.

enabled: Optional[bool]

Specify whether to enable filtering via hosts for egress policies.

inspection: Optional[Inspection]

Define the proxy inspection mode.

mode: Optional[Literal["static", "dynamic"]]

Define the proxy inspection mode. 1. static: Gateway applies static inspection to HTTP on TCP(80). With TLS decryption on, Gateway inspects HTTPS traffic on TCP(443) and UDP(443). 2. dynamic: Gateway applies protocol detection to inspect HTTP and HTTPS traffic on any port. TLS decryption must remain on to inspect HTTPS traffic.

One of the following:
"static"
"dynamic"
protocol_detection: Optional[ProtocolDetection]

Specify whether to detect protocols from the initial bytes of client traffic.

enabled: Optional[bool]

Specify whether to detect protocols from the initial bytes of client traffic.

sandbox: Optional[Sandbox]

Specify whether to enable the sandbox.

enabled: Optional[bool]

Specify whether to enable the sandbox.

fallback_action: Optional[Literal["allow", "block"]]

Specify the action to take when the system cannot scan the file.

One of the following:
"allow"
"block"
tls_decrypt: Optional[TLSSettings]

Specify whether to inspect encrypted HTTP traffic.

enabled: Optional[bool]

Specify whether to inspect encrypted HTTP traffic.

updated_at: Optional[datetime]
formatdate-time

Patch Zero Trust account configuration

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.zero_trust.gateway.configurations.edit(
    account_id="699d98642c564d2e855e9661899b7252",
)
print(response.created_at)
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "settings": {
      "activity_log": {
        "enabled": true
      },
      "antivirus": {
        "enabled_download_phase": false,
        "enabled_upload_phase": false,
        "fail_closed": false,
        "notification_settings": {
          "enabled": true,
          "include_context": true,
          "msg": "msg",
          "support_url": "support_url"
        }
      },
      "block_page": {
        "background_color": "background_color",
        "enabled": true,
        "footer_text": "--footer--",
        "header_text": "--header--",
        "include_context": true,
        "logo_path": "https://logos.com/a.png",
        "mailto_address": "admin@example.com",
        "mailto_subject": "Blocked User Inquiry",
        "mode": "",
        "name": "Cloudflare",
        "read_only": true,
        "source_account": "source_account",
        "suppress_footer": false,
        "target_uri": "https://example.com",
        "version": 1
      },
      "body_scanning": {
        "inspection_mode": "deep"
      },
      "browser_isolation": {
        "non_identity_enabled": true,
        "url_browser_isolation_enabled": true
      },
      "certificate": {
        "id": "d1b364c5-1311-466e-a194-f0e943e0799f"
      },
      "custom_certificate": {
        "enabled": true,
        "id": "d1b364c5-1311-466e-a194-f0e943e0799f",
        "binding_status": "pending_deployment",
        "updated_at": "2019-12-27T18:11:19.117Z"
      },
      "extended_email_matching": {
        "enabled": true,
        "read_only": true,
        "source_account": "source_account",
        "version": 1
      },
      "fips": {
        "tls": true
      },
      "host_selector": {
        "enabled": false
      },
      "inspection": {
        "mode": "static"
      },
      "protocol_detection": {
        "enabled": true
      },
      "sandbox": {
        "enabled": true,
        "fallback_action": "allow"
      },
      "tls_decrypt": {
        "enabled": true
      }
    },
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "created_at": "2014-01-01T05:20:00.12345Z",
    "settings": {
      "activity_log": {
        "enabled": true
      },
      "antivirus": {
        "enabled_download_phase": false,
        "enabled_upload_phase": false,
        "fail_closed": false,
        "notification_settings": {
          "enabled": true,
          "include_context": true,
          "msg": "msg",
          "support_url": "support_url"
        }
      },
      "block_page": {
        "background_color": "background_color",
        "enabled": true,
        "footer_text": "--footer--",
        "header_text": "--header--",
        "include_context": true,
        "logo_path": "https://logos.com/a.png",
        "mailto_address": "admin@example.com",
        "mailto_subject": "Blocked User Inquiry",
        "mode": "",
        "name": "Cloudflare",
        "read_only": true,
        "source_account": "source_account",
        "suppress_footer": false,
        "target_uri": "https://example.com",
        "version": 1
      },
      "body_scanning": {
        "inspection_mode": "deep"
      },
      "browser_isolation": {
        "non_identity_enabled": true,
        "url_browser_isolation_enabled": true
      },
      "certificate": {
        "id": "d1b364c5-1311-466e-a194-f0e943e0799f"
      },
      "custom_certificate": {
        "enabled": true,
        "id": "d1b364c5-1311-466e-a194-f0e943e0799f",
        "binding_status": "pending_deployment",
        "updated_at": "2019-12-27T18:11:19.117Z"
      },
      "extended_email_matching": {
        "enabled": true,
        "read_only": true,
        "source_account": "source_account",
        "version": 1
      },
      "fips": {
        "tls": true
      },
      "host_selector": {
        "enabled": false
      },
      "inspection": {
        "mode": "static"
      },
      "protocol_detection": {
        "enabled": true
      },
      "sandbox": {
        "enabled": true,
        "fallback_action": "allow"
      },
      "tls_decrypt": {
        "enabled": true
      }
    },
    "updated_at": "2014-01-01T05:20:00.12345Z"
  }
}