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.
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.
Vercel custom domains: add them with the API
How to add a custom domain to a Vercel project from code: attach it with the REST API, give your customer the A or CNAME record Vercel recommends, verify ownership with a TXT record, and track it until it is active.
Railway custom domains: DNS, SSL, and the API
How Railway custom domains work, from the CNAME and verification TXT record to automatic Let's Encrypt SSL, and how to add, check, and remove Railway domains from TypeScript.
