Issue and validate certificates

Once you have set up your Cloudflare for SaaS application, you can start issuing and validating certificates for your customers.

​​ Issue new certificates

For each custom hostname certificate you request, Cloudflare issues two certificates that are bundled in chains that maximize browser compatibility (unless you upload custom certificates). The primary certificate uses a P-256 key, is SHA-2/ECDSA signed, and will be presented to browsers that support elliptic curve cryptography (ECC). The secondary or fallback certificate uses an RSA 2048-bit key, is SHA-2/RSA signed, and will be presented to browsers that do not support ECC.

Once issued, certificates are valid for one year. Renewals depend on your chosen method for Domain Control Validation.

​​ Via the dashboard

1. Log in to the Cloudflare dashboard Open external link and select your account.
2. Select your Cloudflare for SaaS application.
3. Navigate to SSL/TLS > Custom Hostnames.
4. Click Add Custom Hostname.
5. Add your customer’s hostname app.customer.com and set the relevant options, including:
   • Choosing the Validation method.
   • Whether you want to Enable wildcard, which adds a *.<custom-hostname> SAN to the custom hostname certificate. For more details, refer to Hostname priority.
   • Choosing a value for Custom origin server.
6. Click Add Custom Hostname.

​​ Via the API

To create a custom hostname using the API, use a POST command Open external link on the /zone/:zone_id/custom_hostnames endpoint.

The response contains the complete definition of the new custom hostname.

​​ Validate certificates

​​ 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

• API Open external link : 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 Open external link with the same values as your initial POST request.

​​ Email

• API Open external link : 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.

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 Open external link with the same values as your initial POST request.

​​ CNAME (manual)

Since this method is only available using the API, you need to make a POST request Open external link 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 Open external link 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)

• API Open external link : 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 Open external link 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.

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.