Skip to content
Visit SSL on GitHub
Set theme to dark (⇧+D)

Getting started

Configure zone with proxy fallback origin

The fallback origin is used to route the traffic of your Custom Hostnames. The fallback record is the value of the DNS record you set up via step 2 below.

  1. Sign up your desired zone at and select the Free plan.
  2. Add a DNS record pointing to the origin (fallback origin) for Cloudflare to send custom hostname traffic. This hostname is not provided to customers. Name the hostname according to your naming convention. For example:
  3. Set up an additional DNS CNAME record to serve as the CNAME target for your end customers. CNAME this record to your fallback origin, and use a more user-friendly CNAME target for customers. This record can optionally be a wildcard, e.g. *
  4. Upgrade your zone to an Enterprise plan.
  5. Retrieve your zone’s
  6. Set the fallback origin via API (change to the fallback origin record you configured in Cloudflare DNS):
$ curl -XPUT"<ZONE_ID>/custom_hostnames/fallback_origin"\-H "X-Auth-Email: {email}" -H "X-Auth-Key: {key}"\-H "Content-Type: application/json"\-d '{"origin":""}'

Certificate Validation vs Hostname Verification

Each Custom Hostname requires successful Certificate Validation and Hostname Verification.

Create Custom Hostnames via the custom_hostnames API endpoint.

API key and zone ID

Your API key can be found in the Cloudflare dashboard under ‘My Profile → Global API Key’.

Accessing an account’s Global API Key

The zone tag and API key can also be found in the ‘Overview’ tile of the UI:

Obtaining a zone’s ID

Additionally you can retrieve a list of user’s zones and their associated IDs via an API call. List all zones for a user:

Issuing your first certificate

Once your account has been provisioned, you are ready to issue certificates. The call below will provision a request for certificates to be issued for, which represents your end customer.

In this example, HTTP based validation is used ("method":"http") to issue this certificate. This requires HTTP traffic to be proxied through Cloudflare’s edge already, i.e., the CNAME from must be in place to your zone. If the CNAME is not yet in place, Cloudflare will ask its CA partner to retry until the request can be completed; see the Validation Backoff Schedule for specific timings.

$ curl -XPOST ""\       -H "X-Auth-Email: {email}" -H "X-Auth-Key: {key}"\       -H "Content-Type: application/json"\       -d '{"hostname":"", "ssl":{"method":"http","type":"dv"}}'

Note that it’s possible to serve these HTTP records from your own web servers, in advance of placing the CNAME. The payload returned includes the path where the CA will look for the challenge along with the body that should be returned.

Once domain validation has been completed, the certificates will be issued and distributed to Cloudflare’s edge. With a CNAME in place, the entire process—from validation to issuance to edge deployment—completes in approximately 90 seconds.