UniFi Network
UniFi API key setup: use a matching Site Manager or local Network API key to read and manage a site's flat DNS records through the Cloud Connector or trusted HTTPS.
On this page
UniFi API key permissions
- Credential type
- UniFi API key
- Preview access
- API-key owner can list Network sites and DNS policies or legacy static-DNS entries
- Apply access
- API-key owner can create, update, and delete Network DNS policies or legacy static-DNS entries
- API endpoint
- You provide a public API endpoint.
Additional access
DNSControl id
{
"TYPE": "UNIFI"
}Create credentials
Use a matching Site Manager or local Network API key to read and manage a site's flat DNS records through the Cloud Connector or trusted HTTPS.
Access you'll grant
API-key owner can list Network sites and DNS policies or legacy static-DNS entries
API-key owner can create, update, and delete Network DNS policies or legacy static-DNS entries
Before you start
- A UniFi Gateway running the Network application and an administrator allowed to create API keys.
- For Cloud Connector access, UniFi console firmware 5.0.3 or later and a UI account or organization key with access to that console.
- For direct access, a public hostname with trusted TLS and a firewall or proxy restricted to our egress IP.
Setup steps
0 of 7 done
Choose remote or direct access
Prefer Console ID (remote access) when the console is linked to UniFi Site Manager: DNSMigrator reaches it through
api.ui.com, so no inbound management port is exposed. Use Controller URL only when you can safely publish the console toour egress IP. Enter one mode, not both.Create a local Network key
For direct access, open the Network application, then Settings → Control Plane → Integrations, and create an API key under the administrator whose Network permissions should govern it. Copy the key and use it only with Controller URL.
Create a Site Manager key
For remote access, sign in to UniFi Site Manager, open Settings → API Keys, generate a key, and copy it immediately because it is shown once. A personal key reaches only its owner's consoles; an organization key can reach consoles in that organization.
Copy the remote console ID
For Cloud Connector mode, use the console/host
idreturned by Site Manager'sGET /v1/hosts; it is also represented in UniFi Site Manager console URLs. Paste the complete value, including any colon suffix, into Console ID (remote access).List accessible hostscurl --fail https://api.ui.com/v1/hosts -H 'X-API-KEY: <site-manager-api-key>' -H 'Accept: application/json'Restrict a direct controller URL
Skip this step for Console ID mode. For direct mode, install a publicly trusted certificate and allow only
our egress IPto the HTTPS endpoint. DNSMigrator calls over the public Internet. Its SSRF guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses, validates every DNS answer, and pins one validated IP. The default self-signed console certificate is not accepted.Select the site and API
Leave Site empty for
default; for the Integration API, DNSMigrator also matches the local site's internal reference or display name. Leave API at Detect automatically to try/integration/v1/.../dns/policiesfirst and fall back to/v2/api/site/.../static-dns. Force a mode only for troubleshooting.Default settingsSite: default API: Detect automaticallyEnter the matching key and endpoint
Paste the local key with Controller URL, or the Site Manager key with Console ID (remote access). Check access and inspect a preview before applying. UniFi stores records as a flat site-wide list rather than authoritative zones.
Troubleshooting
401 or “UniFi rejected the API key”
Match the key type to the access mode. A local Network key is not a Site Manager key, and a Site Manager key should be used with Console ID.
The site is not found
Use default or copy the site's internal reference/display name. Legacy mode expects the legacy site name; new mode resolves the site to its API ID.
Direct access fails TLS or endpoint validation
Replace the self-signed certificate with a publicly trusted chain and use a hostname whose complete DNS answer set is public; allow our egress IP at every firewall layer.
Remote preview works but apply is forbidden
The check does not write. Confirm the key owner can change Network settings and that the Site Manager key supports Cloud Connector write methods; otherwise use a local Network key through the restricted direct endpoint.
Official documentation
- UniFi: developer documentation
- UniFi Network API: DNS policies
- UniFi Network API: Cloud Connector GET
- DNSControl: UniFi provider
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| API keyapiKey | Required | Use the key created for the selected mode: local Network Integration key for Controller URL, or Site Manager key for Console ID. |
| Controller URLhost | Optional | Direct mode only: public trusted-HTTPS console origin. DNSMigrator adds /proxy/network; leave empty in remote mode. |
| Console ID (remote access)consoleId | Optional | Remote mode only: complete host ID from Site Manager GET /v1/hosts or the console URL. Leave empty in direct mode. |
| Sitesite | Optional | Legacy site name or Integration API internal reference/display name. Leave empty for default. |
| APIapiVersion | Optional | Use auto normally. new forces Integration DNS policies; legacy forces the v2 static-dns endpoint. |
Capabilities
- Create zones
- No
- List zones
- No
- DNSSEC
- Not available through this connection
- Minimum TTL
- Automatic
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- MX
- TXT
- SRV
Caveats
- Consoles usually sit on a private network; we refuse private addresses by design, so either use the console ID (reached through api.ui.com) or expose the console publicly over HTTPS.
- A publicly trusted TLS certificate is required when connecting directly: we never skip certificate verification, so the console's default self-signed certificate will not work.
- Records are one flat list per site (no zones); only A, AAAA and CNAME have a configurable TTL, and TXT values are limited to 255 characters without double quotes.
Troubleshooting
- 401 or “UniFi rejected the API key”
- Match the key type to the access mode. A local Network key is not a Site Manager key, and a Site Manager key should be used with Console ID.
- The site is not found
- Use default or copy the site's internal reference/display name. Legacy mode expects the legacy site name; new mode resolves the site to its API ID.
- Direct access fails TLS or endpoint validation
- Replace the self-signed certificate with a publicly trusted chain and use a hostname whose complete DNS answer set is public; allow {egressIp} at every firewall layer.
- Remote preview works but apply is forbidden
- The check does not write. Confirm the key owner can change Network settings and that the Site Manager key supports Cloud Connector write methods; otherwise use a local Network key through the restricted direct endpoint.