# Managed DNS

> Point a domain's nameservers at us once.

Source: https://docs.customdomain.ai/docs/dns/managed-dns

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](/docs/concepts/glossary#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](/docs/guides/nameserver-migration) 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)](/docs/guides/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:

| 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 `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

```json
"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

```bash
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](#next-name)). A zone already hosted for another account answers `409`.

The response, and every other managed DNS response, is the zone:

```json
{
  "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}`:

```json
"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:

```bash
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

```bash
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

```bash
  -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](/docs/dns/root-domains).
