Troubleshooting

If your query returns an error even after configuring and embedding a client SSL certificate, check the following settings.

On your terminal, use the following command to check whether an SSL/TLS connection can be established successfully between the client and the API endpoint.

curl --verbose --cert /path/to/certificate.pem --key /path/to/key.pem https://your-api-endpoint.com

If the SSL/TLS handshake cannot be completed, check whether the certificate and the private key are correct. If the handshake completes but requests are still blocked, confirm that Cloudflare is verifying the client certificate.

Check whether mTLS has been enabled for the correct host. The host should match the API endpoint that you want to protect.

To review mTLS rules, consider the steps below. For further guidance refer to Custom rules.

1. In the Cloudflare dashboard, go to the Security rules page.

   Go to Security rules ↗

2. On a specific rule, select Edit.

3. On that rule, check whether:

   • The Expression Preview is correct.

   • The hostname, if defined, matches your API endpoint. For example, for the API endpoint api.trackers.ninja/time, the rule should look like:

     (http.host in {"api.trackers.ninja"} and not cf.tls_client_auth.cert_verified)

4. To edit the rule, either use the user interface or select Edit expression.

You can use Cloudflare Workers to debug client certificate validation failures.

1. Create a Worker to debug print cf.properties:

   export default {
     async fetch(request, env, ctx) {
       console.info({ message: JSON.stringify(request.cf, null, 2) });
       return new Response(JSON.stringify(request.cf, null, 2))
     }
   };

2. Associate the Worker with the hostname where mTLS is enabled using a Worker route or a Custom Domain.

3. Make requests to the hostname and/or path configured, with and without sending the mTLS client certificate.

4. View your logs on the Observability dashboard and compare the responses against the expected values listed below.

   Go to Observability ↗

• Valid certificate

  "tlsClientAuth": {
    "certPresented": "1",
    "certVerified": "SUCCESS",
  },

• Invalid certificate (for example, self-signed certificates)

  "tlsClientAuth": {
    "certPresented": "1",
    "certVerified": "FAILED:self signed certificate",
  },

• No certificate

  "tlsClientAuth": {
    "certPresented": "0",
    "certVerified": "NONE",
  },

Cloudflare-managed client certificates count against a per-zone quota. To free up a slot, revoke certificates you no longer need. Revoking a certificate immediately releases the slot.

To list and revoke certificates, refer to the client certificates API.

Each Enterprise account can upload up to five CA certificates for BYOCA. This quota is shared across API Shield, Workers mTLS, and Cloudflare Gateway.

If you exceed this limit, the API returns:

{
  "code": 1489,
  "message": "Hit maximum CA cert allocation."
}

To free a slot, you must first remove all hostname associations from the CA before deleting it. To increase your quota, contact your account team.

When uploading a CA certificate for Bring your own CA (BYOCA), the certificate must meet the following requirements:

• The CA certificate can be from a publicly trusted CA or self-signed.

• In the certificate Basic Constraints, the attribute CA must be set to TRUE.

• The certificate must use one of the signature algorithms listed below:

  Allowed signature algorithms

  x509.SHA1WithRSA

  x509.SHA256WithRSA

  x509.SHA384WithRSA

  x509.SHA512WithRSA

  x509.ECDSAWithSHA1

  x509.ECDSAWithSHA256

  x509.ECDSAWithSHA384

  x509.ECDSAWithSHA512

The certificate you upload must be a CA certificate — that is, it must have Basic Constraints: CA=TRUE in its extensions. It is the certificate that directly issued your client certificates, not a client certificate itself.

A common cause of upload failure is uploading a leaf (client) certificate instead of the CA certificate. If your certificate chain is Root CA → Intermediate CA → Client certificate, upload the Intermediate CA (which has CA:TRUE), not the client certificate.

To confirm whether a certificate is a CA certificate, run:

openssl x509 -in certificate.pem -noout -text | grep -A1 "Basic Constraints"

The output should include CA:TRUE. If it shows CA:FALSE or the field is absent, the certificate is not a CA certificate and cannot be uploaded.

The CA certificate must use one of the following signature algorithms:

• SHA1WithRSA, SHA256WithRSA, SHA384WithRSA, SHA512WithRSA
• ECDSAWithSHA1, ECDSAWithSHA256, ECDSAWithSHA384, ECDSAWithSHA512

If the CA certificate uses a different algorithm, re-issue it using a supported one.

The certificates field in the upload request must contain valid, properly delimited PEM content. Ensure the certificate starts with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----. Do not include private keys or certificate signing requests in this field.