Managed DNS
Point a domain's nameservers at us once.
Sometimes a domain's DNS provider offers no sign-in, one-click setup, secure sign-in or API key that fits. Then the only other way to connect it is to add the records in the provider's panel by hand. That is where most connections stall. Managed DNS replaces the typing with one change the domain's owner makes once: set the domain's nameservers to CustomDomain™'s. From then on, CustomDomain™ hosts the whole zone and writes every record, now and later. The console and the widget call it DNS hosting, the sixth of the ways to connect. The API calls it managed DNS and, for the move itself, nameserver migration.
Managed DNS is rolling out gradually, so
POST /v1/domains:check tells you whether it is available for a domain.
Your end users are offered it only when your application turns it on. One
setting decides every DNS hosting offer the widget makes. It is the
application's DNS hosting setting (nameserver_migration, which the
nameserver migration guide calls Domain
maintenance). With it on, the widget asks each end user once, with their
consent. It moves their nameservers either to CustomDomain™ or to a DNS host of
your own: Cloudflare, Amazon Route 53, Google Cloud DNS, Azure DNS, or your own
nameservers. See Domain maintenance (nameserver
migration). With it off (the default), the
widget offers no DNS hosting, even where managed_dns.available is true. From
your own server, with an API key or an app-scoped token, you can start managed
DNS for any connection either way.
How it works
- Check.
POST /v1/domains:checkreturns"managed_dns": {"available": true, "reason": ""}when the domain can be hosted. - Start.
POST /v1/connections/{id}/managed-dnscreates a hosted zone for the connection's registrable domain. That isacme.com, also when the connection isshop.acme.com. It copies the records the domain serves today, adds the records the connection needs, and looks up the registrar. - Switch. The domain's owner replaces the domain's nameservers, at its
registrar, with the
nameserversin the response. Nothing changes for anyone until they do, and because the zone already holds the domain's records, nothing breaks when they do. - Active. CustomDomain™ reads the delegation from the domain's registry
(the
.comservers foracme.com). Once every listed nameserver is ours, the zone turnsactive, the connection is verified right away, and it goes live.
After that, CustomDomain™ writes every record change for the connection into the
zone. That covers a www redirect switched on, a CAA opt-in, a :reapply and a
disconnect. Nobody is asked to edit DNS again.
The next name under an active zone
Once the zone is active, the next name under the same registrable domain needs
no start and no switch. An example is blog.acme.com, after shop.acme.com.
When it is created with POST /v1/connections, it joins the zone. Its records
are written into the zone and checked at once, and the answer can already say
live. Nobody is asked again.
A zone is one customer's whole DNS, so only the right caller joins it:
- A widget token, only when the zone is the token's own. The rule is the same as for every other managed DNS call of a widget token (see "Whose zone it is", below). The new connection is the token's, and so is every connection already linked to the zone, in the same application. The application must still offer DNS hosting on CustomDomain™'s own DNS. Who started the zone does not decide it. Once your API key, or another end user, has a name in the zone, it is no longer that end user's. So their next name does not join it.
- An API key, or an app-scoped token, for the application the zone was started in.
- Never a delegated agent token, a token that does not own the zone, another application or another workspace. Those names prove control by DNS, as before, and nothing is written into the zone.
Each join is in the workspace's audit log as dns.hosted_zone_joined.
Copying the existing records
DNS has no way to list a zone, so before the switch CustomDomain™ asks the domain's current nameservers about the names domains commonly use and copies what they serve:
- the root:
A,AAAA,MX,TXT,CAA www,mail,webmail,smtp,imap,pop,autodiscover,autoconfig_dmarc, and the DKIM selectors of common mail services (google,selector1,selector2,k1,k2,s1,s2,default,mandrill,mailjet,resend,zoho,protonmailtoprotonmail3,fm1tofm3,dkim,mxvault)- the SRV names of common chat and mail services (
_sip._tls,_sipfederationtls._tcp,_autodiscover._tcp,_imaps._tcp,_submission._tcp) - every name the connection itself uses
A CNAME is copied as the CNAME (never the addresses it leads to), and a
wildcard is copied as a wildcard. The zone's own NS and SOA are never
copied: those become CustomDomain™'s.
Names outside that list are not found this way. Before switching, check the record list, and import a zone file or add anything that is missing. Most DNS providers can export a zone file.
DNSSEC. The zones CustomDomain™ hosts are not signed yet. DNSSEC may be
turned on for the domain at its registrar, which means the registry publishes a
DS record. Then resolvers that validate DNSSEC would stop answering for the
domain after the switch. The zone's warnings say so while a DS record
exists. Turn DNSSEC off at the registrar when you change the nameservers.
Where records come from
Each record carries a source. When sources disagree about a name, the higher
one wins:
| Source | Meaning | Wins over |
|---|---|---|
customdomain | Needed by CustomDomain™ to serve a connected domain | everything |
manual | Added by hand | imported, discovered |
imported | From a zone file | discovered |
discovered | Copied from the old DNS |
What "wins" means:
- A
CNAMEcan't share its name. So a higherCNAMEremoves everything below it at that name, and a lowerCNAMEgives way to anything above it. - A zone file is authoritative for what it defines: an imported
MXset replaces the copiedMXset. - Records added by hand are added: adding a second
MXkeeps the first. - A name can hold only one
v=spf1, onev=DMARC1, onev=DKIM1TXT record. - Where CustomDomain™ points a name (
shop.acme.comto the edge), older addresses for that name are removed, includingAAAA. No visitor is sent to the old host.
Every record that was replaced or skipped is explained in warnings.
API
Availability
"managed_dns": { "available": false, "reason": "platform_subdomain" }reason is "" when available. Otherwise it is disabled (off on this
deployment), platform_subdomain (someone.github.io: the name belongs to a
hosting platform), unsupported_tld (no registrable domain whose nameservers a
registrar can change) or reserved.
This is the deployment's and the domain's verdict only. It doesn't say whether
your application offers DNS hosting to its end users. That is the
nameserver_migration block of the same response, present only when the
application's setting is on.
Start
curl -X POST https://api.customdomain.ai/v1/connections/<ID>/managed-dns \
-H "Authorization: Bearer cd_live_…"201 the first time, 200 after that with the same zone. A repeat call also
re-reads the delegation (at most every 30 seconds), which is how a "check
now" button works. A second connection under the same registrable domain joins
the existing zone (an active zone is joined without this call, for the callers
above). A zone already hosted for another account answers 409.
The response, and every other managed DNS response, is the zone:
{
"zone": "acme.com",
"status": "awaiting_delegation",
"nameservers": ["ns-1402.awsdns-47.org", "ns-905.awsdns-49.net", "ns-106.awsdns-13.com", "ns-1860.awsdns-40.co.uk"],
"observed_nameservers": ["ns1.olddns.net", "ns2.olddns.net"],
"registrar": { "name": "GoDaddy.com, LLC", "url": "https://www.godaddy.com" },
"records": [
{ "id": "mdr_3c1f...", "type": "MX", "name": "acme.com", "value": "aspmx.l.google.com", "ttl": 3600, "priority": 1, "source": "discovered" },
{ "id": "mdr_9a07...", "type": "CNAME", "name": "shop.acme.com", "value": "edge.customdomain.ai", "ttl": 3600, "priority": null, "source": "customdomain" }
],
"warnings": ["Before you switch nameservers, check that every record acme.com uses is listed. ..."],
"checked_at": "2026-09-26T12:00:00Z",
"activated_at": null
}registrar is null when the registry doesn't say. status is
awaiting_delegation, active or failed.
Read
GET /v1/connections/{id}/managed-dns returns the zone, or 404 when managed
DNS was never started for the connection. Poll it while status is
awaiting_delegation.
Find the domains you host
Every connection carries dns_hosting, on GET /v1/connections and on
GET /v1/connections/{id}:
"dns_hosting": { "state": "hosted", "by": "customdomain", "zone": "acme.com", "since": "2026-10-01T09:00:00Z" }state is one of four values. hosted means the nameservers point at the zone,
so it is what the world resolves. moving means the zone is being set up, or
the nameservers are being moved. failed means the zone never became active, or
the domain moved its nameservers away again. none carries nothing else. by
is customdomain for managed DNS here, dns_host for your own account at a DNS
host (provider names it) and custom for your own nameservers. zone is the
domain or the parent domain that is hosted: shop.acme.com is hosted when
acme.com is.
A zone you started with the call above counts as soon as it is active, with no
move to a registrar through nameservers:migrate. To list the domains you
host, filter the connection list:
curl "https://api.customdomain.ai/v1/connections?dns_hosting=hosted" \
-H "Authorization: Bearer cd_live_…"hosted keeps the domains served from a zone we run. moving keeps those being
set up or moved. any keeps every domain with hosting in play: hosted, moving
or failed. The filter pages like the unfiltered list, so follow next_cursor.
Any other value is a 400. Another account's zone never counts, and a test mode
connection is never hosted.
On the detail read, an API key, an app-scoped token and an agent token also get
reach. It says how CustomDomain™ writes the domain's DNS. kind is account,
sign_in, domain_connect, dns_hosting, route53_role or none.
can_reapply says whether :reapply can write now. managed_possible says
whether the one-click sign-in can be offered for the domain's provider here. A
hosted domain is reached by its hosting, whoever runs the zone. An agent token
reads reach and the connection's credential with less. The key's customer
number, sign-in session and name are left out. label reads <Provider> key
for a key made for another application, because the label the agent chose names
that application's domain.
Import a zone file or add records
curl -X POST https://api.customdomain.ai/v1/connections/<ID>/managed-dns/records \
-H "Authorization: Bearer cd_live_…" \
-H "Content-Type: application/json" \
-d '{ "zone_file": "$ORIGIN acme.com.\n@ 3600 IN MX 10 mail.acme.com.\n" }'or
-d '{ "records": [
{ "type": "TXT", "name": "@", "value": "google-site-verification=abc" },
{ "type": "MX", "name": "@", "value": "mx2.mailhost.net", "priority": 20 }
] }'Send exactly one of zone_file or records. Names may be relative (@,
www, _dmarc) or fully qualified inside the zone. Supported types: A,
AAAA, CNAME, MX, TXT, SRV (value "<weight> <port> <target>",
priority separate), CAA and NS (for subdomains only).
The zone file parser reads BIND format. It understands $ORIGIN, $TTL (also
1h, 2d), @, relative and absolute names, a blank name (the line above's),
comments, parentheses, and quoted and multi-string TXT. Anything it can't host
is skipped with a warning naming the line. That covers the SOA, the zone's own
NS records, other types, names outside the zone, $INCLUDE and $GENERATE.
A record added by hand that would override a customdomain record is refused
with 409; an imported one is skipped with a warning.
Remove a record
DELETE /v1/connections/{id}/managed-dns/records/{record_id} removes one
record and returns the zone. customdomain records can't be removed (409):
disconnect the domain instead. Record ids are derived from the record's
content, so they stay the same across reads.
Who can call what
The routes are authorized like the other connection routes. That means an API key for any connection in the tenant, or a widget token of the connection's own application and domain. Changes need a role that can write connections.
An end user's connect-scoped widget token can start managed DNS only when
the application offers DNS hosting on CustomDomain™. Its nameserver_migration
mode must be offer or prefer and its target managed. With the setting off,
the start answers 403 with "this application does not offer nameserver
migration". With the target dns_host or custom, your users' DNS goes to your
own DNS host or nameservers. Then the start answers 403 with "this application
hosts its users' DNS elsewhere; the nameserver move is its offer". Either way no
zone is created. A connection that already has a zone can still call the start,
to resume it, and read or edit its records as below. An API key or an app-scoped
token is not limited by the setting.
Once a zone is active it answers for the whole domain, email included, so an
end user's connect-scoped widget token may only read it. Records can still
be changed with an API key or an app-scoped token.
Whose zone it is. One zone serves a whole registrable domain (acme.com for
shop.acme.com and blog.acme.com), so an end user's widget token acts only on
what is its own. The connection the call is about must be the token's: a
connection that names another customer (its end_user_ref is not the token's)
answers 403 token_wrong_end_user on every managed DNS route (POST and GET
.../managed-dns, POST .../managed-dns/records, DELETE .../managed-dns/records/{record_id}) and on the nameserver routes
(GET .../nameservers, :migrate, :rollback), before anything is read, created,
linked or changed. A connection you made with your API key names no customer and is
a token's only when its domain is one the token is bound to (domain or domains):
a token with no end_user_ref and no domain counts only the domain of the
connection the call is about, and a token with an end_user_ref and no domain owns
none of those. A zone that already exists
is started, joined, read or changed only when every connection linked to it is the
token's too; another customer's zone, a zone that also holds a connection you made
with your API key for another name, and a zone nobody is linked to answer 409
with "the DNS of acme.com is already hosted by CustomDomain™ for someone else",
and show none of the zone. A nameserver move whose connection was removed names no
connection: an end user's call on it answers 403 token_wrong_end_user and never
takes it over, and only your API key resumes it. An API key and an app-scoped token
are not limited by any of this.
Limits
| Limit | Value |
|---|---|
| Records per zone | 500 |
| Zone file size | 256 KB |
| Records per request | 500 |
| Zones per account | 100 by default (MANAGED_DNS_MAX_ZONES_PER_TENANT) |
| TTL | Default 3600 seconds; values outside 60 to 604800 are clamped |
Errors
| Status | Code | When |
|---|---|---|
400 | invalid_request | Both or neither of zone_file and records were sent, or more than 500 records in one request |
409 | conflict | The zone belongs to another account, a hand-added record would override a customdomain record, a customdomain record was deleted, or another change to the zone is in progress |
403 | forbidden | An end user's widget token started managed DNS for an application that doesn't offer DNS hosting, or that hosts its users' DNS on its own DNS host or nameservers |
403 | token_wrong_end_user | An end user's widget token acted on a connection that names another customer, or on a nameserver move that is not its own |
413 | payload_too_large | The zone file is over 256 KB |
422 | managed_dns_unavailable | Managed DNS isn't available for this domain (see the availability reason) |
422 | managed_dns_limit | The account already holds its maximum number of zones |
422 | too_many_records | The change would take the zone past 500 records |
422 | invalid_zone_file | The zone file has no records that can be hosted |
503 | service_unavailable | Managed DNS is switched off on this deployment |
Delegation states
| Status | Meaning |
|---|---|
awaiting_delegation | The zone holds the records; the domain still uses other nameservers. Checked every few minutes for the first day, hourly after. |
active | Every nameserver the registry lists is ours. Re-checked every 6 hours. |
failed | The switch didn't happen within 14 days, or the nameservers later moved away. The first warning says which. A failed zone is still checked twice a day and turns active as soon as the delegation appears. |
The registry may list some of our nameservers and some others. Then the zone
stays awaiting_delegation, with a warning naming the extra ones. Resolvers
that pick one of them would still get the old answers.
Root domains
A hosted zone can't alias a hostname outside it. So a root domain (acme.com)
is pointed at the edge with A records to the platform's published apex
addresses (APEX_A_TARGETS). A deployment without them can't host a root
connection's records, and the zone says so in warnings. Connect www instead.
See Root domains.