Bring your own CA for API Shield mTLS

This page explains how you can manage mTLS with API Shield using client certificates that have not been issued by Cloudflare CA.

This is especially useful if you already have mTLS implemented and client certificates issued by your chosen CA are already installed on devices.

​​ Availability

• Currently, you can only upload your CA via API.
• This process is only available on Enterprise accounts.
• Each Enterprise account can upload up to five CAs. This quota does not apply to CAs uploaded through Cloudflare Access.

​​ Set up mTLS with your CA

1. Use the Upload mTLS certificate endpoint Open API docs link to upload the CA root certificate.

2. Take note of the certificate ID (id) that is returned in the API response.
3. Use the Replace Hostname Associations endpoint Open API docs link to enable mTLS in each hostname that should use the CA for mTLS validation. Use the following parameters:

4. Create a custom rule to enforce client certificate validation. You can do this via the dashboard or via API, using the Create firewall rules endpoint Open API docs link .

  "expression": "(http.host in {\"<HOSTNAME_1>\" \"<HOSTNAME_2>\"} and not cf.tls_client_auth.cert_verified)", 
  "action": "block"

​​ Delete an uploaded CA

If you want to remove a CA that you have previously uploaded, you must first remove any hostname associations that it has.

1. Make a request to the Replace Hostname Associations endpoint Open API docs link , with an empty array for hostnames and specifying your CA certificate ID in mtls_certificate_id:

  "hostnames": [], 
  "mtls_certificate_id": "<CERTIFICATE_ID>"

2. Use the Delete mTLS certificate endpoint Open API docs link to delete the certificate.