Domain SDK
Providers

Cloudflare for SaaS custom hostnames: setup and API

How Cloudflare for SaaS custom hostnames work: the fallback origin, the CNAME target your customers point to, hostname and certificate validation, and a TypeScript client for the Custom Hostnames API.

Cloudflare for SaaS custom hostnames let your customers serve your app on their own domain through your Cloudflare zone. You set it up once: create a proxied DNS record for your origin and set it as the zone's fallback origin, then (optionally, but Cloudflare recommends it) create a proxied CNAME target such as customers.yourapp.com that points to the fallback origin. For each customer, you create a custom hostname in the zone, the customer adds a CNAME from their hostname (for example app.customer.com) to your CNAME target, and Cloudflare validates the hostname and issues its TLS certificate. Creating, checking, and deleting each customer hostname is a call to the /zones/{zone_id}/custom_hostnames API, which this adapter wraps.

As of 2026-10-29, Cloudflare's plans page lists 100 custom hostnames included on the Free, Pro, and Business plans, $0.10 for each additional hostname, and a 50,000-hostname maximum. Wildcard custom hostnames and apex proxying are Enterprise features. The blog's Cloudflare for SaaS guide explains how pending hostnames are billed.

Scope and credentials

The adapter creates, retrieves, lists, and deletes Custom Hostnames in one zone. It does not create zone DNS records, configure a fallback origin, or manage customer DNS. Set CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID, and CLOUDFLARE_CNAME_TARGET. Use a scoped API token with Custom Hostnames/SSL permissions for only the SaaS zone.

domains.ts
import { createDomainClient } from "@opencoredev/domain-sdk";
import { cloudflareSaaS } from "@opencoredev/domain-sdk/cloudflare";

export const domains = createDomainClient({
  provider: cloudflareSaaS({
    apiToken: process.env.CLOUDFLARE_API_TOKEN!,
    zoneId: process.env.CLOUDFLARE_ZONE_ID!,
    cnameTarget: process.env.CLOUDFLARE_CNAME_TARGET!,
  }),
});
const domain = await domains.add("app.customer.com");

DNS, verification, and certificates

The configured CNAME target becomes the routing record. ownership_verification becomes ownership DNS; ssl.validation_records become certificate DNS. HTTP validation is preserved as a safe message because it is not a DNS record. A hostname becomes active only when both custom-hostname and SSL states are active.

Errors and limitations

Structured Cloudflare error arrays are sanitized and normalized. Configure a valid fallback/default origin in Cloudflare before adding hostnames; an invalid origin is platform configuration, not customer DNS. v0.1 does not expose wildcards, generic DNS mutation, or apex routing.

Official references: Custom Hostnames, create hostnames, and hostname validation.

Read next: Ownership verification, and the blog's Cloudflare for SaaS guide for validation methods, pricing, and common errors.