Cloudflare Docs
Ssl
Cloudflare Docs
SSL
Search icon (depiction of a magnifying glass)
GitHub icon
Visit SSL on GitHub
Set theme to dark (⇧+D)

Validate certificates — SSL for SaaS

Before a Certificate Authority will issue a certificate for a domain, the requestor must prove they have control over that domain. This process is known as domain control validation (DCV).

DCV methods

If you want to pre-validate your customer’s certificate before they set a CNAME record — either to avoid downtime or prevent any issuance errors — explore TXT , Email , or HTTP (manual) , or CNAME validation.

If you create custom hostnames with wildcards, use TXT or Email validation.

If you value simplicity and your customers can tolerate a few minutes of downtime, use HTTP (automatic) validation.

TXT record

TXT record validation requires the creation of a TXT record in the hostname’s authoritative DNS. Once you create a new hostname via the dashboard or via the API and choose this validation method, you will see the following values after a few seconds:
  • API: Within the ssl object, refer to the values present in the validation_records array (specifically txt_name and txt_value).
  • Dashboard: When viewing an individual certificate at SSL/TLS > Custom Hostnames, refer to the values for Certificate validation TXT name and Certificate validation TXT value.

Ask your customer to create a TXT record named the name and containing the value at their authoritative DNS provider. Once this TXT record is in place, validation and certificate issuance will automatically complete.

If you would like to request an immediate recheck, rather than wait for the next retry , send a PATCH request with the same values as your initial POST request.

Email

Email based validation will send an approval email to the contacts listed for a given domain in WHOIS, along with the following addresses: admin@, administrator@, hostmaster@, postmaster@, and webmaster@. Once you create a new hostname via the dashboard or via the API and choose this validation method, you will see the following values after a few seconds:
  • API: Within the ssl object, refer to the values present in the validation_records array (specifically emails).
  • Dashboard: When viewing an individual certificate at SSL/TLS > Custom Hostnames, refer to the value for Certificate validation email recipients.

The addresses listed in this field will receive an email from support@certvalidate.cloudflare.com. They should either click Review Certificate Request or the https://certvalidate.cloudflare.com hyperlink.

Certificate Validation Email

As soon as the domain owner has clicked the link in this email and clicked Approve on the validation page, the certificate will move through the various statuses until it becomes Active.

If you would like to request an immediate recheck, rather than wait for the next retry , send a PATCH request with the same values as your initial POST request.

CNAME (manual)

If you use Digicert as your Certificate Authority (CA), you can complete DCV with a special CNAME record.

Since this method is only available using the API, you need to make a POST request and set a "method":"cname" parameter.

Within the ssl object in the response, refer to the values present in the validation_records array. Each record will contain a property for cname and cname_target (you can also access these values in the dashboard by clicking that specific hostname certificate). Provide these values to your customer so they can add a CNAME record at their authoritative DNS provider.

If you would like to request an immediate recheck, rather than wait for the next retry , send a PATCH request with the same values as your initial POST request.

HTTP

HTTP adds a DCV token to your origin. You can either add that token manually to support pre-validation or wait for Cloudflare to add the DCV token automatically , which may lead to a few minutes of downtime.

HTTP (manual)

Once you create a new hostname via the dashboard or via the API and choose this validation method, you will see the following values after a few seconds:
  • API: Within the ssl object, store the values present in the validation_records array (specifically http_url and http_body).
  • Dashboard: When viewing an individual certificate at SSL/TLS > Custom Hostnames, refer to the values for Certificate validation request and Certificate validation response.

At your origin, make the http_body available in a TXT record at the path specified in http_url. This path should also be publicly accessible to anyone on the Internet so your CA can access it.

Here is an example NGINX configuration that would return a token:

location "/.well-known/pki-validation/ca3-0052344e54074d9693e89e27486692d6.txt" {
        return 200 "ca3-be794c5f757b468eba805d1a705e44f6\n";
}

Once your configuration is live, test that the DCV text file is in place with curl:

$ curl "http://http-preval.example.com/.well-known/pki-validation/ca3-0052344e54074d9693e89e27486692d6.txt"
ca3-be794c5f757b468eba805d1a705e44f6

On the next check cycle, Cloudflare will ask the CA to recheck the URL, complete validation, and issue the certificate.

If you would like to request an immediate recheck, rather than wait for the next retry , send a PATCH request with the same values as your initial POST request.

HTTP (automatic)

If you value simplicity and your customers can handle a few minutes of downtime, you can rely on Cloudflare automatic HTTP validation.

Once you create a new hostname via the dashboard or via the API and choose the http validation method, all your customers have to do is add a CNAME to your $CNAME_TARGET and Cloudflare will take care of the rest.

What happens after you create the custom hostname

Cloudflare contacts one of our Certificate Authority providers and asks them to issue certificates for the specified hostname. The CA will then inform Cloudflare that we need to “demonstrate control” of this hostname by returning a $DCV_TOKEN at a specified $DCV_FILENAME; both the token and the filename are randomly generated by the CA and not known to Cloudflare ahead of time.

For example, if you create a new custom hostname for site.example.com, the CA might ask us to return the value ca3-38734555d85e4421beb4a3e6d1645fe6 for a request to http://site.example.com/.well-known/pki-validation/ca3-39f423f095be4983922ca0365308612d.txt". As soon as we receive that value from the CA we make it accessible at our edge and ask the CA to confirm it’s there so that they can complete validation and the certificate order.

If you would like to complete the issuance process before asking your customer to update their CNAME (or before changing the resolution of your target CNAME to be proxied by Cloudflare), choose another validation method.

Renew certificates issued by DCV

If you are using a proxied hostname, new certificates are automatically validated via HTTP .

If you need to use another validation method — for example, if you are using wildcard certificates or certificates with multiple SANs — you need to repeat the DCV process with your chosen method and share the tokens with your customer.