Create custom hostnames

There are several required steps before a custom hostname can become active. For more details, refer to our Get started guide.

To create a custom hostname:

Dashboard

1. In the Cloudflare dashboard, go to the Account home page and select your account.

   Go to Account home

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:

   • The minimum TLS version.
   • Defining whether you want to use a certificate provided by Cloudflare or upload a custom certificate.
   • Selecting the certificate authority (CA) that will issue the certificate.
   • 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.

Default behavior

When you create a custom hostname:

• If you issue a custom hostname certificate with wildcards enabled, you cannot customize TLS settings for these wildcard hostnames.
• If you do not specify the Minimum TLS Version, it defaults to the zone's Minimum TLS Version. You can still edit this setting after creation.

API

1. To create a custom hostname using the API, use the Create Custom Hostname endpoint.

   • You can leave the certificate_authority parameter empty to set it to "default CA". With this option, Cloudflare checks the CAA records before requesting the certificates, which helps ensure the certificates can be issued from the CA.

2. For the newly created custom hostname, the POST response may not return the DCV validation token validation_records. It is recommended to make a second GET command (with a delay) to retrieve these details.

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

Default behavior

When you create a custom hostname:

• If you issue a custom hostname certificate with wildcards enabled, you cannot customize TLS settings for these wildcard hostnames.
• If you do not specify the Minimum TLS Version, it defaults to the zone's Minimum TLS Version. You can still edit this setting after creation.

For each custom hostname, Cloudflare issues two certificates 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.

Hostnames over 64 characters

The Common Name (CN) restriction establishes a limit of 64 characters (RFC 5280 ↗). If you have a hostname that exceeds this length, you can set cloudflare_branding to true when creating your custom hostnames via API.

"ssl": {
    "cloudflare_branding": true
  }

Cloudflare branding means that sni.cloudflaressl.com will be added as the certificate Common Name (CN) and the long hostname will be included as a part of the Subject Alternative Name (SAN).