Skip to content
DNSmigrator
betaDNS betaSelf-hostedSetup guide checked 2026-09-27

PowerDNS Authoritative

PowerDNS API key setup: enable the PowerDNS Authoritative HTTP API behind a restricted public HTTPS endpoint and connect with its server-wide API key.

On this page

PowerDNS API key permissions

Credential type
API key
Preview access
X-API-Key access to the server and zone read endpoints
Apply access
The same server-wide API key; PowerDNS does not offer a scoped or read-only API key
API endpoint
You provide a public API endpoint.

Additional access

The access check only reads /api/v1/servers/<server ID>, then reports read/write. It does not attempt a write, so confirm the endpoint and key policy before applying.

DNSControl id

creds.json TYPE
{
  "TYPE": "POWERDNS"
}

Create credentials

Enable the PowerDNS Authoritative HTTP API behind a restricted public HTTPS endpoint and connect with its server-wide API key.

Access you'll grant

Preview

X-API-Key access to the server and zone read endpoints

Apply

The same server-wide API key; PowerDNS does not offer a scoped or read-only API key

The access check only reads /api/v1/servers/<server ID>, then reports read/write. It does not attempt a write, so confirm the endpoint and key policy before applying.

Before you start

  • PowerDNS Authoritative with permission to edit pdns.conf and restart the service.
  • A public hostname, a publicly trusted TLS certificate, and a firewall or reverse proxy that can allow-list our egress IP.

Setup steps

0 of 6 done

  1. Generate a strong API key

    Generate a dedicated random secret and keep it in your secret manager. PowerDNS sends this value in the X-API-Key header.

    Generate 32 random bytesopenssl rand -base64 32

  2. Enable the API on a local listener

    Add these settings to pdns.conf. Keeping the built-in HTTP server on loopback avoids exposing unencrypted port 8081; put a TLS reverse proxy in front of it.

    pdns.confapi=yes api-key=<strong-random-secret> webserver=yes webserver-address=127.0.0.1 webserver-port=8081 webserver-allow-from=127.0.0.1,::1

  3. Publish a restricted HTTPS endpoint

    Proxy a public hostname such as pdns.example.com to 127.0.0.1:8081, install a publicly trusted certificate, and allow only our egress IP. DNSMigrator calls from its servers over the public Internet. Its SSRF guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses; it checks every DNS answer and pins one validated IP for the connection.

  4. Restart and test the server endpoint

    Restart PowerDNS, then request the native server ID. A direct PowerDNS Authoritative server uses localhost; a different ID is only appropriate when an external proxy presents multiple servers.

    Restartsystemctl restart pdns
    Test HTTPS APIcurl --fail --header 'X-API-Key: <api-key>' https://pdns.example.com/api/v1/servers/localhost

  5. Enter the connection values

    Paste the public origin into API URL, the secret into API key, and localhost into Server ID unless a multi-server proxy documents another value. The URL may end at the origin or at /api/v1.

  6. Set new-zone defaults

    If DNSMigrator may create zones, enter authoritative servers in Nameservers for new zones and choose Native (database replication) or Primary (AXFR/NOTIFY to secondaries) under Kind for new zones. These values do not alter existing zones.

    Nameserver formatns1.example.net., ns2.example.net.

Troubleshooting

The endpoint is refused as private or non-public

Use a public DNS name whose complete answer set is public. Split-horizon names, private addresses, CGNAT, metadata, and reserved/documentation ranges are intentionally blocked.

401, 403, or “PowerDNS rejected the API key”

Compare the pasted value with api-key in pdns.conf, confirm api=yes, and ensure the reverse proxy preserves the X-API-Key header.

Server localhost is not found

Remove a duplicated /api/v1 path and use server ID localhost. Only a multi-server API proxy should require a custom ID.

The check says write access but apply is denied

The check is read-only. Review proxy method restrictions and PowerDNS logs; allow POST, PUT, PATCH, and DELETE on the required /api/v1 paths.

Official documentation

Guide checked against the official documentation on .

Credential fields

FieldRequirementWhere to find it
API URLapiUrlRequiredThe public HTTPS origin for PowerDNS, optionally ending in /api/v1. Do not enter a private address or the loopback port.
API keyapiKeyRequiredThe exact api-key value from pdns.conf. It grants server-wide API access.
Server IDserverIdOptionalUse localhost for a native PowerDNS Authoritative server. Change it only when your API proxy explicitly supplies another server ID.
Nameservers for new zonesdefaultNameserversOptionalComma- or whitespace-separated FQDNs for zones DNSMigrator creates; trailing dots are recommended. Leave empty for existing zones only.
Kind for new zoneszoneKindOptionalCreation-only zone kind: Native for database replication, or Master for a primary that sends AXFR/NOTIFY. Existing zones keep their kind.

Capabilities

Create zones
Yes
List zones
Yes
DNSSEC
Managed through the API
Minimum TTL
Automatic
Apex CNAME
No
Read only
No

Record types

  • A
  • AAAA
  • CNAME
  • MX
  • TXT
  • NS
  • SRV
  • CAA
  • PTR
  • DS
  • HTTPS
  • SVCB
  • TLSA
  • SSHFP
  • NAPTR
  • SPF
  • CERT
  • URI
  • DHCID
  • DNAME
  • OPENPGPKEY
  • SMIMEA
  • RP
  • ALIAS

PowerDNS-only types

  • LUA

These records need translation or review when you move to another provider.

Caveats

  • We only connect to public HTTPS addresses: expose the PowerDNS webserver through a reverse proxy with TLS and allow-list our egress IPs; private or internal addresses are refused.
  • ALIAS records only resolve if expand-alias and a resolver are configured on the server, and DNAME needs dname-processing.
  • Disabled records are not imported, and an RRset we update is replaced as a whole, so disabled entries inside it are dropped.

Troubleshooting

The endpoint is refused as private or non-public
Use a public DNS name whose complete answer set is public. Split-horizon names, private addresses, CGNAT, metadata, and reserved/documentation ranges are intentionally blocked.
401, 403, or “PowerDNS rejected the API key”
Compare the pasted value with api-key in pdns.conf, confirm api=yes, and ensure the reverse proxy preserves the X-API-Key header.
Server localhost is not found
Remove a duplicated /api/v1 path and use server ID localhost. Only a multi-server API proxy should require a custom ID.
The check says write access but apply is denied
The check is read-only. Review proxy method restrictions and PowerDNS logs; allow POST, PUT, PATCH, and DELETE on the required /api/v1 paths.

Related links

PowerDNS Authoritative migration overviewMarketing overview and provider differences.Connect a providerHow connection checks and permissions work.Cloudflare → PowerDNSRoute 53 → PowerDNSAzure DNS → PowerDNSCloud DNS → PowerDNS