Cloudflare Docs
Cloudflare for Platforms
Cloudflare for Platforms
Visit Cloudflare for Platforms on GitHub
Set theme to dark (⇧+D)

Verify custom hostnames

Cloudflare verifies ownership of each new hostname before traffic is allowed to proxy. There are four methods to verify ownership: TXT record, HTTP token, CNAME, or Apex.

​​ CNAME

​​ Full setup

Cloudflare iterates over the CNAME chain starting from the hostname. The value of the last CNAME must contain the domain that owns the custom hostname record. For example, if the domain owning the custom hostname record is saasprovider.com, then the CNAME looks similar to app.example.com CNAME proxy-fallback.saasprovider.com

​​ Partial setup

​​ If using Cloudflare for a partial setup

  1. Add a CNAME record to Cloudflare DNS for your domain:
app.example.com CNAME proxy-fallback.saasprovider.com
  1. Add a CNAME record to your authoritative DNS to point to the fallback origin:
proxy-fallback.saasprovider.com CNAME proxy-fallback.saasprovider.com.cdn.cloudflare.net

​​ If using another DNS provider

  1. Log in to your authoritative DNS provider.
  2. Add a CNAME record to point to the fallback origin owned by the SaaS provider.
app.example.com CNAME proxy-fallback.saasprovider.com

​​ Apex Proxying

If you have an Enterprise account, you can utilize Apex verification (after talking with your account team).

For verification, the account that owns the custom hostname must also own all A and AAAA records for the apex. To verify ownership, the IP returned for the hostname must reside in the IP prefix allocated to the account.

When you are adding a new custom hostname to Cloudflare, the few seconds Cloudflare requires to iterate over the CNAME can cause a slight downtime. This is likely acceptable for CNAME verification of Custom Hostnames for staging or development sites. However, Cloudflare recommends verification of Custom Hostnames via TXT record or HTTP token for live production traffic. When TXT or HTTP verification completes and the Custom Hostname shows Active in the Cloudflare SSL/TLS app under the Custom Hostnames tab, inform your customer to CNAME traffic to Cloudflare.

​​ TXT

Each API call to create a Custom Hostname provides a TXT ownership_verification record for your customer to add to their DNS for ownership validation of the Custom Hostname.

{
"result": [
{
"id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
"hostname": "app.example.com",
// ...
"status": "pending",
"verification_errors": ["custom hostname does not CNAME to this zone."],
"ownership_verification": {
"type": "txt",
"name": "_cf-custom-hostname.app.example.com",
"value": "0e2d5a7f-1548-4f27-8c05-b577cb14f4ec"
},
"created_at": "2020-03-04T19:04:02.705068Z"
}
]
}

​​ HTTP

Each API call to create a Custom Hostname also provides an HTTP ownership_verification record. Compared to TXT verification, HTTP verification doesn’t require your customer to change their DNS. HTTP verification is used mainly by organizations with a large deployed base of custom domains with HTTPS support. Serving the HTTP token from the zone’s origin server allows hostname verification before proxying domain traffic through Cloudflare.

To get and use an HTTP ownership_verification record:

  1. Make an API call to create a Custom Hostname.

  2. In the response, copy the http_url and http_body from the ownership_verification_http object:

Example response (truncated)
{
"result": [
{
"id": "24c8c68e-bec2-49b6-868e-f06373780630",
"hostname": "app.example.com",
// ...
"ownership_verification_http": {
"http_url": "http://app.example.com/.well-known/cf-custom-hostname-challenge/24c8c68e-bec2-49b6-868e-f06373780630",
"http_body": "48b409f6-c886-406b-8cbc-0fbf59983555"
},
"created_at": "2020-03-04T20:06:04.117122Z"
}
]
}
  1. Store the http_url and http_body on your origin web server.
Example configuration
location "/.well-known/cf-custom-hostname-challenge/24c8c68e-bec2-49b6-868e-f06373780630" {
  return 200 "48b409f6-c886-406b-8cbc-0fbf59983555\n";
}
  1. After a few minutes, you will see the hostname validation become Active in the UI.

​​ Error codes

Various hostname verification errors include:

Error MessageCause
Zone does not have a fallback origin setFallback is not active.
Fallback origin is initializing, pending_deployment, pending_deletion, or deletedFallback is not active.
Custom hostname does not CNAME to this zoneZone does not have apex proxying entitlement and custom hostname does not CNAME to zone.
None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not foundAccount has apex proxying enabled but the custom hostname failed the hostname validation check on the A record.
This account and the pre-generated ownership verification token was not foundHostname does not CNAME to zone or none of the A/AAAA records match reserved IPs for zone.

​​ Verification statuses

Applicable hostname verification status includes:

Verification Status MessagesDescription
PendingCustom hostname is pending hostname verification.
ActiveCustom hostname has completed hostname verification and is active.
Active re-deployingCustomer hostname is active and the changes have been processed.
BlockedCustom hostname cannot be added to Cloudflare at this time. Custom hostname was likely associated with Cloudflare previously and flagged for abuse. If you are an Enterprise customer, please contact your Customer Success Manager. Otherwise, please email abusereply@cloudflare.com with the name of the web property and a detailed explanation of your association with this web property.
MovedCustom hostname is not active after Pending for the entirety of the Validation Backoff Schedule, or it no longer points to the fallback origin.
DeletedCustom hostname was deleted from the zone. Occurs when status is Moved for more than 7 days.