CustomDomain Docs
DNS and serving

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

  1. Check. POST /v1/domains:check returns "managed_dns": {"available": true, "reason": ""} when the domain can be hosted.
  2. Start. POST /v1/connections/{id}/managed-dns creates a hosted zone for the connection's registrable domain. That is acme.com, also when the connection is shop.acme.com. It copies the records the domain serves today, adds the records the connection needs, and looks up the registrar.
  3. Switch. The domain's owner replaces the domain's nameservers, at its registrar, with the nameservers in the response. Nothing changes for anyone until they do, and because the zone already holds the domain's records, nothing breaks when they do.
  4. Active. CustomDomain™ reads the delegation from the domain's registry (the .com servers for acme.com). Once every listed nameserver is ours, the zone turns active, 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, protonmail to protonmail3, fm1 to fm3, 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:

SourceMeaningWins over
customdomainNeeded by CustomDomain™ to serve a connected domaineverything
manualAdded by handimported, discovered
importedFrom a zone filediscovered
discoveredCopied from the old DNS

What "wins" means:

  • A CNAME can't share its name. So a higher CNAME removes everything below it at that name, and a lower CNAME gives way to anything above it.
  • A zone file is authoritative for what it defines: an imported MX set replaces the copied MX set.
  • Records added by hand are added: adding a second MX keeps the first.
  • A name can hold only one v=spf1, one v=DMARC1, one v=DKIM1 TXT record.
  • Where CustomDomain™ points a name (shop.acme.com to the edge), older addresses for that name are removed, including AAAA. 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

LimitValue
Records per zone500
Zone file size256 KB
Records per request500
Zones per account100 by default (MANAGED_DNS_MAX_ZONES_PER_TENANT)
TTLDefault 3600 seconds; values outside 60 to 604800 are clamped

Errors

StatusCodeWhen
400invalid_requestBoth or neither of zone_file and records were sent, or more than 500 records in one request
409conflictThe 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
403forbiddenAn 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
403token_wrong_end_userAn end user's widget token acted on a connection that names another customer, or on a nameserver move that is not its own
413payload_too_largeThe zone file is over 256 KB
422managed_dns_unavailableManaged DNS isn't available for this domain (see the availability reason)
422managed_dns_limitThe account already holds its maximum number of zones
422too_many_recordsThe change would take the zone past 500 records
422invalid_zone_fileThe zone file has no records that can be hosted
503service_unavailableManaged DNS is switched off on this deployment

Delegation states

StatusMeaning
awaiting_delegationThe zone holds the records; the domain still uses other nameservers. Checked every few minutes for the first day, hourly after.
activeEvery nameserver the registry lists is ours. Re-checked every 6 hours.
failedThe 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.

On this page