Providers
Connecting providers
Connect a DNS provider with the least access needed for preview or apply. Add credentials, run access checks, read connection status, and remove access.
5 min read
On this page
A provider connection lets DNSMigrator read zones for previews and, when the credential permits it, write after the relevant confirmation. The key point is that access is checked when you connect and can be checked again at any time, but the permission itself is set at the provider—not expanded by DNSMigrator.
Before you connect#
Decide how the account will be used. A source connection only needs enough access to list and read the zones you plan to move. A destination connection needs create or write access before DNSMigrator can apply a plan. Registrar access is separate and is used during nameserver cutover.
Start with the narrowest credential that supports the job:
| Use | Access to grant | What DNSMigrator does |
|---|---|---|
| Preview a source | Read zones and record sets | Lists zones, reads the selected zone and builds a record-by-record preview |
| Apply to a destination | Read and write zones and record sets | Reads live state again, creates the destination zone when supported, then applies the newly calculated plan |
| Cut over automatically | Registrar nameserver access; DS access when supported | Changes delegation and handles supported DNSSEC registry steps |
| Guided cutover | No registrar API credential required | Shows each registrar action and checks public DNS for completion |
Provider APIs use different permission names. Open the provider’s generated guide under Supported providers for the exact fields and scopes. For example, see Cloudflare, Amazon Route 53 or Namecheap.
Add a connection#
You need the Admin or Owner role to create a connection. Members can see existing connections and use active ones to build previews, but the server rejects connection changes from a Member account.
Open the provider picker
In the app, go to Connections and select Connect a provider. Use Search providers or the All, Cloud, CDN, DNS hosting, Registrar and Self-hosted filters to find the service.
Read the provider requirements
Select the provider. The dialog shows its authentication method, required permissions, setup steps and links to its official documentation. If it is marked Beta, preview before applying; the adapter has been tested against recorded responses but not yet against a live account.
Create the credential at the provider
Follow the provider guide and copy only the requested values. Keep the provider console open until the access check succeeds. Do not put usernames, passwords or tokens inside an endpoint URL; use the separate fields in the form.
Name and connect it
Enter a recognizable value in Name, fill every required field, and select Connect. The button changes to Checking access… while DNSMigrator validates the fields, encrypts the credential and calls the provider’s access endpoint.
Review the result
A successful check shows the connection as Active and reports Read or Read + write when the adapter can determine scope. If the credential can be stored but the check fails, the connection remains saved as Access failed with the provider’s safe error message. Fix the provider-side setting, then select Check access.
Choose read or write access#
Most providers do not expose a read/write switch in DNSMigrator. You choose the scope while creating the API token, service account or provider user, then DNSMigrator checks what that credential can do. Grant read access for previews. Add write access only to connections that will be destinations or managed-zone targets.
Route 53 is the exception in the dialog. DNSMigrator uses a cross-account IAM role in production instead of long-lived AWS access keys. Leave Include write access (needed to apply to Route 53) selected for a destination, or clear it for a read-only source, then select Open CloudFormation. The generated stack trusts DNSMigrator’s AWS account and binds the role assumption to the workspace’s external ID. Copy the resulting role ARN into the connection form. The full flow is in the Route 53 provider guide.
Namecheap requires DNSMigrator’s static egress address on the account allow-list. The dialog displays Allow-list followed by that address when the server is configured for Namecheap. If it says Not available on this server yet., the deployment has no static egress IP and the connection cannot be created on that server.
Understand connection status#
The Connections list keeps the latest access result, a non-secret credential hint and the credential deletion time.
| Status | Meaning | Next action |
|---|---|---|
| Active | The latest provider access check succeeded | Use it as a source; use it as a destination only if it shows write access and the provider is writable |
| Not checked | No successful or failed check has been recorded | Select Check access before starting work |
| Access failed | The provider rejected the check or could not be reached | Read the row’s message and follow Troubleshooting access |
| Credentials deleted | The encrypted secret has been purged | Create a new connection to continue; the old migration history remains |
Credential hints deliberately expose only limited context, such as a token suffix, account label or truncated identifier. The full secret is not returned to the browser after it is stored. See Credential security for encryption, audit and deletion details.
Recheck or remove access#
Select Check access after changing token permissions, allow-list rules or provider account settings. The check decrypts the stored credential for that request, calls the same adapter verification used at creation, updates the status and records the use in the activity log.
Select Remove, review the confirmation, then choose Remove and delete credentials to erase the stored secret immediately. DNSMigrator keeps migration history that refers to the connection. Removal is blocked while an apply, verification or rollback is actively using it.
Continue from a connection#
Once both DNS connections are Active, start at Quickstart or open Migrations to choose the source zone and destination. Connect the registrar only when you want DNSMigrator to perform the delegation step; otherwise the guided cutover works without registrar API access.