Domain Connect template

A Domain Connect template is the JSON document a SaaS publishes to describe the DNS records it wants applied to a customer's domain. It is the contract in a Domain Connect integration, the DNS-as-code artifact of the setup flow: the DNS provider fetches it, shows the customer what will change, applies it on consent, and the records go live.

The template is the easy part. Getting a provider to honour yours is the part that decides whether the integration is worth building.

Domainee is a custom domains API for SaaS with a native MCP server — 50 domains and 100 GB free.

What a template contains

{
  "providerId": "yoursaas.com",
  "providerName": "Your SaaS",
  "serviceId": "custom-domain",
  "serviceName": "Custom Domain",
  "version": 1,
  "logoUrl": "https://yoursaas.com/logo.png",
  "description": "Connect your domain to Your SaaS",
  "syncBlock": true,
  "records": [
    { "type": "CNAME", "host": "www",             "pointsTo": "%cname-target%", "ttl": 1800 },
    { "type": "TXT",   "host": "_acme-challenge", "data": "%acme-token%",       "ttl": 60 }
  ]
}

providerId and serviceId together identify the template. A provider that has registered you will reject a template whose providerId does not match the domain it was registered under, which is what stops anyone publishing a template that impersonates you.

version is not decoration. Providers cache templates, and bumping the version is how a change gets picked up. Changing records in place without bumping it produces the worst kind of bug: correct-looking JSON, stale records applied.

Variables are substituted by the provider, not by you

The %...% placeholders are resolved at apply time from query parameters you put in the redirect:

https://dash.cloudflare.com/domainconnect/v2/domainTemplates/providers/yoursaas.com
  /services/custom-domain/apply
  ?domain=customer.com
  &cname-target=customer.yoursaas-edge.com
  &acme-token=BkLi9X...

Two things follow from the provider doing the substitution.

Every variable is customer-visible. It travels in a URL the customer's browser loads and appears on the consent screen. Nothing secret belongs in a template variable. An ACME token is fine — it is a one-time public challenge value. An API key is not.

Signed templates exist for the cases where that matters. Domain Connect supports signing the apply request so a provider can verify the parameters came from you and were not edited in the address bar. If a variable controls where traffic goes, sign it. An unsigned template lets a customer point your www record wherever they like, which is usually harmless and occasionally not.

Keep the TTL low on validation records and moderate on routing records. The _acme-challenge TXT above uses 60 because it is transient; a CNAME at 1800 balances propagation against your ability to move an edge target later.

What not to put in a template

The apex is the recurring mistake. A template that writes a CNAME at @ is invalid DNS — an apex domain cannot hold a CNAME, because it must carry SOA and NS records and RFC 1034 forbids a CNAME alongside other data. Providers that support CNAME flattening or ALIAS records will accept it and synthesise A records; providers that do not will reject the whole template, taking your www record down with it.

Either publish separate templates for apex-capable and apex-incapable providers, or keep the apex out and handle it with a redirect to www.

Two more worth avoiding: never include records you do not own the meaning of, such as MX, unless the customer explicitly asked you to take over mail — a template that quietly rewrites MX will break their email and the consent screen will not make that obvious enough. And do not bundle several unrelated services into one template, because the customer can only accept or reject the whole thing.

Sync and async templates

	syncBlock: true	Async / OAuth
Customer present	Required	Only for the first consent
Applied when	During the redirect	Any time, over the API
Good for	One-shot setup	Certificate renewal, key rotation, edge moves
You hold	Nothing	A token that can write to the zone

Most platforms need both. The sync template gets the domain connected while the customer is watching; the async one handles what comes later, because a certificate that needs revalidation in sixty days cannot wait for the customer to log in again.

Registration is the real cost

You cannot host a template and expect providers to honour it. Each one registers templates separately, on its own terms:

Provider	How templates are registered
GoDaddy	Application form, manual review
Cloudflare	Partner arrangement
IONOS	Application form
Network Solutions	Contract

Every one is a separate relationship with a separate review, and none of them is instant. This — not the JSON — is why small SaaS products skip Domain Connect. The protocol is good and the rollout is a business-development exercise.

That shapes the sensible build order. Ship copy-paste DNS instructions first, since they work for every customer on every provider. Then measure which DNS hosts your customers actually use, by resolving NS records at signup, and pursue registration only with the one or two that cover most of them. Registering with a provider none of your customers use is pure cost.

How many templates you need

Fewer than it first appears. A template is a service offering, not a customer, so the axes that matter are: apex included or not, ACME validation record included or not, sync or async. Most custom domain platforms land on two to four in total and reuse them across every customer, with the per-customer detail carried entirely in the variables.

Whatever the template says, verify the outcome. A provider can apply records successfully and still leave you unreachable — a pre-existing conflicting record, a proxy setting, a zone that was not the active one. Confirm the CNAME resolves to your target and check propagation before marking setup complete, exactly as you would for the manual path. DNS verification is the same job either way.

Debugging a template that applied but did not work

The provider reports success, the customer sees green, and the site is still down. The usual causes, in the order worth checking:

• A conflicting record already existed. Some providers add rather than replace, leaving two www records or an old A record beside your new CNAME. The zone is now ambiguous and resolution depends on which the provider serves. Read the zone back, do not assume your write was the only one.
• The wrong zone. The domain resolves via nameservers at one provider while the customer edited a zone at another — a stale zone file at their old host that nothing consults. The records genuinely exist and are genuinely never queried.
• The provider's proxy is on. Cloudflare's orange-cloud setting makes the record resolve to Cloudflare rather than to your edge, so your CNAME target is correct and unreachable. Certificate validation then fails in a way that looks like your problem.
• The TTL on the old record. The previous value is still cached for its full lifetime, so nothing is wrong except that you checked too early. Confirm against the authoritative server rather than a public resolver before declaring failure.
• A syncBlock template applied to a domain the account does not hold. The consent screen succeeded against a different zone with the same name.

The pattern under all five: the template is a request, not a result. Verify by reading DNS, never by trusting the provider's success response.

Versioning a template that is already live

Templates are long-lived once providers have registered them, and changing one is not like deploying code. A few rules that save trouble:

• Bump version on every record change, and treat the provider's cache as opaque — you cannot force a refresh.
• Never repurpose a serviceId. If the records mean something materially different, publish a new service rather than mutating the old one. Customers who applied the old template do not re-consent, so the meaning of an existing grant must not drift.
• Additive changes are safer than replacements. Adding a TXT record for a new verification step is low risk. Changing where an existing CNAME points moves live traffic for everyone who applied the template.
• Keep the old template resolvable. Providers may fetch it during a re-apply long after you have moved on.

If you need to move an edge target, prefer changing what your existing CNAME target resolves to over changing the target in the template. The indirection exists so you can move without touching a single customer's zone — the same reason you hand out a hostname rather than edge IPs.

FAQ

What is a Domain Connect template? A JSON document a SaaS publishes describing the DNS records it wants applied to a customer's domain, with placeholders for per-customer values. The customer's DNS provider fetches it, shows the records for approval, substitutes the variables and writes them.

Can a Domain Connect template add a CNAME at the apex? Not portably. The apex cannot hold a CNAME, so providers with CNAME flattening or ALIAS support will synthesise something and providers without it will reject the template outright — losing the other records with it. Keep the apex out, or publish a separate template for apex-capable providers.

Are template variables secret? No. They travel as query parameters in a URL the customer's browser loads and are shown on the consent screen. Put only public values in them — an ACME challenge token is fine, an API key is not. Sign the apply request when a variable controls routing.

How do I get my template registered with a DNS provider? Individually, with each one. GoDaddy and IONOS run application forms with manual review, Cloudflare works through a partner arrangement, Network Solutions through a contract. There is no central registry, and this friction is the main reason Domain Connect adoption is thinner than the protocol deserves.

How many templates does a custom domain platform need? Usually two to four. Templates vary by service shape — apex or not, ACME record or not, sync or async — and never by customer, since per-customer values are carried in variables.

What happens if I change a template without bumping the version? Providers cache templates, so a change may not be picked up and stale records get applied while your JSON looks correct. Increment version on every change to the record set.