Domain maintenance (nameserver migration)

Domain maintenance lets your platform keep your users' domains working for them. Each user is asked once, in the widget, when they connect a domain. If they say yes, one setting at the company they bought the domain from changes, and from then on CustomDomain™ (or your own DNS account) runs the domain's DNS: every record your platform needs is written and kept correct, the certificate renews, and problems are fixed without asking the user again. The domain stays registered where it is, and its website and email keep working.

The technical name is nameserver migration, because the one setting that changes is the domain's nameservers. The API, the webhooks and the MCP tools use that name (nameserver_migration, nameservers.*), and so does this page where it describes them.

This page is for the engineer who turns it on, and for anyone who answers a user's questions about it (What changes for your users is at the end).

DNS, the registrar and nameservers

Three words come up everywhere here. In plain terms:

• DNS is the internet's address book. It tells browsers and email where a domain's website and mail live. A domain's DNS settings are called its records.
• The registrar is the company a domain was bought from and is renewed with, like GoDaddy or Namecheap. It is often not the company that runs the domain's DNS: a domain bought at GoDaddy can have its DNS at Cloudflare.
• Nameservers are one setting at the registrar. They say who runs the domain's DNS. Changing them is the only change a move makes.

So a domain has two parts: where it is registered (paid for), which a move never touches, and what keeps it working (its DNS), which a move hands to you.

Behind those two parts are three parties:

Moving the nameservers changes who answers for the domain: the registry stops listing the old DNS host's nameservers and lists the new ones. The registrar, the registration, the renewal date and the owner stay exactly as they were.

What the user gets:

• One change, made once. After it, every record your platform needs is written for them, and records that drift are put back.
• Their website and email keep working. The domain's records are copied to the new DNS host before the nameservers move, and the copy counts the mail records (MX, SPF, DKIM, DMARC) so the screen can say "email included". Nothing changes at the registrar until the copy is in place, and a copy we could only read from outside waits for a person to check it (The copy).
• They can switch back, two ways. To the nameservers they had, while their previous DNS host still answers for the domain (Cloudflare deletes a moved domain's records after 7 days), or to their registrar's own DNS, which is always there. See What moving back does.

Where the nameservers are changed: at the registrar

A domain's nameservers are changed at its registrar, which is often not the company that runs its DNS. Registered at GoDaddy with its DNS at Cloudflare is the most common split, and then the change is made at GoDaddy. So for every move, CustomDomain™ looks the registrar up:

1. In public registration data. A domain's registry publishes who the domain is registered with, over RDAP (the protocol behind the public WHOIS lookup at lookup.icann.org). The answer names the registrar, its website, its IANA Registrar ID and, when the registry shows one, the reseller it was bought through.
2. Matched to a provider we connect to, by that IANA ID: all of GoDaddy's registrar accreditations are GoDaddy, Namecheap's is Namecheap, and so on. A registrar we do not connect to, such as a wholesale registrar that sells through resellers, is named (by the reseller when the registry shows one), and the person makes the change there.
3. Used for every way of making the change. A registrar key, a connected account, a secure sign-in and the manual instructions all go to that registrar. An account at the DNS host is never used for the change, and a key or account at another company than the registrar is refused (422 registrar_mismatch). Without an account linked to the connection, a connected account of the workspace at the registrar that can read the domain's registration is used (for a move your server or the console starts).

When the registry answers nothing, the move goes on with the detected DNS host as a guess and names no company: the next step says to make the change "where acme.com is registered (the company it was bought from; lookup.icann.org names it)". A connected account at that DNS host is used then only when it can read the domain's registration, which shows it is the registrar's. The move carries the registrar as registrar (name, provider, iana_id, url and source), null when it is not known, and the DNS host the domain left as old_dns_host.

Cloudflare Registrar requires Cloudflare's own nameservers, so a domain registered there cannot be moved without transferring it to another registrar first. The domain check says available: false with reason: registrar_locks_nameservers, and a move is refused with 422 registrar_locks_nameservers before anything is copied.

Who runs it: CustomDomain™ or your own account

Each application picks who runs the DNS of the domains it maintains. The console calls this Who runs it; the API calls it the target.

CustomDomain™ uses managed DNS, which is rolling out gradually, so the domain check says per domain whether it can be offered (below).

What your own account needs

Connect the account first as a provider account of the workspace with continuous access, using a key that may create zones (a zone is one domain's set of records at a DNS host):

In the console, Your own account shows a tile for each of these hosts. A host you have connected can be picked (with a choice of account when there are several); one you have not is a link to connect it, and one connected with a key that cannot create zones says so.

Each zone is found or created, never made twice: a retry uses the zone it already made, and a zone that already existed in your account keeps what it holds. Only the connection's own records are written into it, and nothing is deleted.

Your own nameservers

In the console, open Advanced under Your own account, tick Use your own nameservers instead, and list them one per line. Give 2 to 13 nameserver host names. The zone must answer on them before the nameservers move: a move to your nameservers waits in pending until you say the zone is ready (zone_ready: true), then checks that your nameservers answer for the domain (skip_zone_check: true skips that check).

Per application

The setting, the DNS host account, the console's figures and the webhooks belong to one application. A move only ever uses its own application's DNS host account (a call that names another application's account is refused with 422 dns_host_not_configured), GET /v1/applications/{id}/nameserver-migrations lists one application's moves, and the nameservers.* webhooks go to the move's own application only.

Turn it on

In the console: Applications, the application, Settings, then Domain maintenance (a test mode application has none). Turn on Maintain your users' domains, choose Who runs it, and Save. Nothing changes for your users until you save. Once saved, each user is asked when they connect a domain. Turned off again, new users are not asked, and domains already maintained stay that way.

With the API, PATCH /v1/applications/{id} with nameserver_migration. The API is the same as before the console's new words: its switches map to mode, and Who runs it to target.

curl -X PATCH https://api.customdomain.ai/v1/applications/<APP_ID> \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "nameserver_migration": { "mode": "prefer", "target": { "kind": "managed" } } }'

Send {"nameserver_migration": {"mode": "off"}} to turn it off. Once it is on, POST /v1/domains:check carries nameserver_migration for the domain (mode, target, available, path, provider, registrar, and reason when available is false, such as registrar_locks_nameservers), and only then. The registrar lookup there waits 3 seconds at most; the move looks again with more time.

What your users see

With Show it as the first choice off, the widget's manual setup shows it as a quiet card beside adding records: "Let Acme Sites keep your domain working", "One change where you bought it. Your website and email keep working." With it on, the manual path opens on the consent screen, and Add records instead is one tap away.

The widget asks once, in plain words. The title names your platform and the domain ("Let Acme Sites keep acme.com working?"), and under it are "Your domain stays where you bought it. Only one setting there changes.", the nameservers now and after, "Your website and email keep working. Nothing changes until your settings are in place.", "You can switch back any time." and one button, Yes, set it up. For a domain whose DNS is at Cloudflare it adds "Switching back to Cloudflare works for 7 days. After that you switch back to GoDaddy's own DNS." (the registrar's name, or "your registrar"). It is white label: your platform's name, never ours. The id and version of that consent text (nsm-consent, version 3) are stored with the move and the time; the person's address is not. A widget's move must name a consent text the widget shows (nsm-consent versions 1 to 3), so a stored consent always names the words that were on the screen.

Then the same screen shows its progress (copy settings, security check, make the change, live) and the next thing to do: a copy to check ("Check the copy before anything changes.", then Looks right, continue), the nameservers to type at the registrar, a button to sign in to the registrar with secure sign-in, or that we are waiting on the registry. The registrar is named only when it is known; otherwise the screen says "your registrar", never the DNS host's name. Move back is there while it can be, with the other way back beside it when both are possible. A finished move hands over to the usual success screen. Every string is in the widget's 13 languages.

What each status means

A domain's page in the console shows three steps: Copying settings (pending, copying, needs_review), Waiting for the registrar (needs_dnssec_off through propagating) and Live (active). Domains you maintain and the domain's badge give its status in plain words, the first column here:

Why a move stopped, as failure_code and as the console says it:

A zone has one open move at a time, so two connections under one registrable domain (acme.com and shop.acme.com) share it, and a move of the same zone for another account is refused with 409.

The copy

The new DNS host must hold every record the domain relies on before the nameservers move, or the switch takes the website and the mail down. There are two ways to know them, and the move says which in copy_source:

• api: the whole zone, read through the old DNS host's API. When CustomDomain™ holds a key at the DNS host the domain uses now (a sign-in kept for the connection, or a connected account there), every record is read through that host's API. Such a copy is proven complete, unless a record could not be carried over (a forwarding rule, or a root CNAME a host flattens), which copy_warnings names.
• discovery: read from public DNS. Public DNS cannot list a domain's records, so the names domains commonly use are asked one by one. Such a copy is never proven, and the move waits in needs_review until a person checks copy_warnings and confirms it. Your server may accept it in advance by sending copy_reviewed: true with the start; a copy that read nothing at all always waits for a person, and in the widget only after the end user saw it. For a domain whose DNS is at Cloudflare, records that answer with Cloudflare's proxy addresses are not copied as if they were the website's own address: they are left out and named, so the person adds the real addresses or connects the Cloudflare account.
• existing_zone (your own account only): your zone already held records, which are kept; only the connection's own records are written.

Nothing changes at the registrar until the copy is at the new DNS servers: a copy whose write failed is retried, never switched to. When a person confirms a copy, the time is kept (copy_reviewed_at).

How the nameservers change

No standard lets a third party ask a registrar to change a domain's nameservers. Domain Connect changes records only, and CDS and CSYNC (RFC 7344, RFC 7477) need the current DNS host to publish them and the domain to be signed with DNSSEC, which most domains are not. So each move takes one of three paths:

A registrar's answer is not taken at its word. Before a change, the registrar is read: it must still list the nameservers the move started from, so a change someone made there since is never overwritten (the move stops with changed_elsewhere). After an error, the registrar (then the registry) is read back, because a timeout can come after the registrar acted: the new nameservers mean the change happened, the old ones mean it did not (registrar_refused), and no answer leaves the move in setting with waiting_for: registrar_confirm.

What each registrar's API can do:

Secure sign-in can change the nameservers at Namecheap, GoDaddy and Name.com, where it is offered, and choose the registrar's own DNS at Namecheap ("Namecheap BasicDNS") and GoDaddy ("GoDaddy Nameservers"). A lasting API key made at sign-in counts as a connected account (at GoDaddy with GoDaddy's permission), and it changes the nameservers only for domains of the application it was made for. A key is never read during a move's own sign-in.

Why DNSSEC comes first

DNSSEC is a security lock some domains have on their DNS: the registry publishes a DS record, and resolvers use it to check that answers come from the domain's DNS host. When the registry publishes one, the nameservers must not move until it is gone and resolvers have dropped it, or validating resolvers would stop answering for the domain. With a connected account that keeps access (path api) at a registrar whose API removes DS records (Name.com and Porkbun), we remove it and wait (waiting_ds). Otherwise the move stops at needs_dnssec_off, the workspace's owners and admins get a "needs attention" notification, and the secure sign-in path offers a session whose only step is turning DNSSEC off. Some registrars turn DNSSEC on by default (Squarespace and Spaceship among them), so expect it.

The new DNS host does not sign the zone. Turning DNSSEC on again there is the DNS host owner's choice after the move.

What moving back does

A domain can be moved back two ways, and a move back names one in rollback_target:

Without a choice, a move back goes to the previous nameservers while they still answer, and to the registrar's own DNS once they do not. The move says which: rollback_default is where a plain move back goes, rollback_targets lists the ways possible now (previous is left out once the old nameservers stopped answering), and old_dns_serves says whether they still answered when last asked (once a day while the move is active, and at a move back). A domain that used the registrar's own DNS when the move started goes back through the registrar's own reset, not by setting its old names as custom ones.

How it is made, in rollback_path:

• api: through the registrar's API, at once (rollback_set_at), with a key sent once or the move's connected account. For the registrar's own DNS, this is its reset call where it has one: Namecheap, Spaceship, Name.com, Porkbun and Hostinger (table above).
• agent: the end user signs in to the registrar with secure sign-in (purpose: nameservers) and approves the move back: the old nameservers, or the registrar's own DNS. This is the way to the registrar's own DNS at GoDaddy, and elsewhere without a key.
• manual: next_step says what to set, or what to choose at the registrar.
• none: nothing had changed at the registrar yet, so the move is just stopped.

A move back reads the registrar first. It must still list the move's nameservers: if someone changed them since, the answer is 409 changed_elsewhere and nothing is written. A list already where the move back goes (an earlier answer lost) counts as done. A registrar error is read back too: 502 registrar_refused when nothing changed, 504 registrar_unconfirmed when it cannot tell, and nothing is recorded then, so try again. Any secure sign-in still working on the move is ended first. It is idempotent, and the nameservers.rolled_back webhook says where it went (rollback_target).

In the console, the domain's DNS tab offers the default way first (Move back, or Move back to GoDaddy's DNS once the old nameservers no longer answer) and, beside it, the other one when it is possible. Each asks first ("Move acme.com back?") and says what it does: "Its nameservers go back to the ones it had before. Its previous provider still answers for it, so it works as before.", or "It goes back to GoDaddy's own DNS, with the records it held there before the move. Records changed since then are not in it." In the widget, your user sees the same two buttons.

A move back does not yet copy the connection's records into the registrar's DNS, restore how the connection was written before the move, or delete the zone the move created.

API

Start a move from your server through the customer's connected registrar account:

curl -X POST https://api.customdomain.ai/v1/connections/<ID>/nameservers:migrate \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "path": "api", "provider_account_id": "pacct_…" }'

To use a key once instead, send provider (the registrar's id, such as porkbun) and credential: {"token": "…"} in the registrar's key format; it is used for that call and never stored.

201 creates the move and 200 resumes the domain's open one with what the call brings (a key, zone_ready, copy_reviewed once a person checked the copy). The answer is the move as far as it got in that call: with a registrar key and no DNSSEC it is often already propagating. Poll GET /v1/connections/{id}/nameservers until state is active, failed or rolled_back. waiting_for says what it waits on and next_step is one sentence for a person. The shape is illustrative; the API reference has every field under Nameservers.

The 422 refusals say why a move cannot start: nameserver_migration_unavailable (details says why), nameserver_api_unsupported (the registrar has no API call that changes nameservers), nameserver_agent_unavailable (secure sign-in cannot change this registrar's nameservers), registrar_locks_nameservers (Cloudflare Registrar, above), registrar_mismatch (the key or account is at another company than the domain's registrar), zone_host_unsupported or dns_host_not_configured.

Agent tokens never choose where the nameservers go. A delegated agent token (an AI agent acting for a person) may start a move only to the application's own target, and may not send skip_zone_check; anything else is refused with 403 target_not_allowed. With a registrar account linked, nameservers an agent chose would hand it the whole domain in one call. Your own API key may still name managed or custom.

A move back takes {"rollback_target": "previous"} or {"rollback_target": "registrar_default"}, or nothing for the default (What moving back does). Its refusals: 409 old_dns_gone (the old nameservers no longer answer: move back to the registrar's own DNS instead), 409 changed_elsewhere (the registrar lists other nameservers than the move's), 502 registrar_refused (nothing changed) and 504 registrar_unconfirmed (the answer was lost and could not be read back: try again).

Webhooks

Seven events follow a move. Each carries a nameservers object and is written to the domain's timeline as a row of the same kind. When they are known, the object also names the registrar (name, provider, iana_id) and the old_dns_host, and on nameservers.rolled_back it says where the move back went (rollback_target). See the event catalog and the payload.

MCP

The MCP server has three tools for it: check-nameserver-status (domains:read), and migrate-nameservers and rollback-nameservers (domains:connect, both with confirm: true, which an agent sends only after the person agreed). The tools never send a registrar key. With an agent token, migrate-nameservers refuses target and nameservers: the application's setting decides where the nameservers go, and the control plane refuses the same (403 target_not_allowed). migrate-nameservers takes copyReviewed once the agent showed the person the copy's warnings and they agreed, and rollback-nameservers takes target (previous or registrar_default). Results carry registrar, oldDnsHost, copySource, copyWarnings, rollbackDefault and rollbackTargets.

In the console

• Application settings, Domain maintenance: the switch Maintain your users' domains, a before and after picture of a user's domain (where it is registered stays; what keeps it working moves to CustomDomain™ or your host), Who runs it (CustomDomain™, or your own Cloudflare, Amazon Route 53, Google Cloud DNS or Azure DNS account, with your own nameservers under Advanced), and Show it as the first choice. A ? beside DNS, registrar and nameservers gives one plain line and a link here, and every card links to the part of this page that explains it.
• Domains you maintain, under it once it is on: how many domains are maintained, being set up and need attention, the typical setup time, why moves stopped, and one row per domain with who runs it, its status in plain words, the records copied and when it was last checked. Each row opens the domain.
• A domain's DNS tab: a Domain maintenance section with its status, the three steps, the next thing to do, for a copy to check what to check and The records look right, continue, the domain's two parts (naming the registrar, with its logo, only when it is known), where its records are (listed below for CustomDomain™; a count and a link to your host's console for your own account), its nameservers under Technical details, and the ways back: Move back, and Move back to GoDaddy's DNS beside it or in its place. A domain your own DNS host runs is not offered CustomDomain™'s managed DNS there.
• Webhooks: a Nameserver moves group in the event picker. The domain's timeline has a sentence for each event.

A move is not billed on its own: CustomDomain™ bills connected domains, and a zone it hosts counts toward the managed DNS zone limit of the account.

What changes for your users

In the words you can give them.

What am I agreeing to? That the platform keeps your domain working for you. One setting at the company you bought your domain from changes, so the platform can keep your domain's settings correct, renew its certificate and fix problems without asking you again.

Will my website or email stop working? No. Your settings are copied first, email included, and nothing changes until they are in place. If some could only be read from outside, you are asked to check them first.

Does my domain move to another company? No. It stays registered where you bought it, with the same renewal date and the same owner. You keep paying for it there.

What do I have to do? Say yes. Then, unless the change can be made for you, either paste the values shown at the company you bought your domain from, or sign in there and approve the change. The screen tells you which.

How long does it take? Usually minutes. It can take up to 48 hours to show everywhere.

Why do I have to turn off DNSSEC? DNSSEC is a security lock on the old settings. It must be off before they move, or the domain would stop working during the move. You can turn it on again afterwards.

Can I switch back? Yes, any time, two ways. To your previous provider, while it still has your records: some delete them a few days after the domain moves away (Cloudflare after 7). Or to your registrar's own DNS, which is always there, with the records it held before the move.

Who can change my records afterwards? The platform, through the DNS host it uses. You can still ask it to change or show them.