Skip to main content
Get started

How to get a PowerDNS API key

Dennis Postma29 July 2026
Reading time3 minutes
Guides

Enable the PowerDNS webserver and HTTP API, set an api-key in pdns.conf and connect the server to DNSense.

DNSense guide cover: a PowerDNS API key configured in pdns.conf

With PowerDNS you do not get an API key, you choose one. It lives in pdns.conf, and the API only answers once the built-in webserver is switched on. Nothing to log in to. A text file and a restart.

Edit pdns.conf

Add these settings to the configuration of the Authoritative Server:

api=yes
api-key=<a long random string>
webserver=yes
webserver-address=0.0.0.0
webserver-allow-from=<the addresses that may connect>
  • api-key is the secret. Generate it with openssl rand -hex 32. Do not leave the changeme from the documentation in place.
  • webserver-address defaults to 127.0.0.1, so only the server itself can connect. Change it to 0.0.0.0 or the public IP of the nameserver for remote access.
  • webserver-allow-from lists the netmasks that may connect. Keep it as narrow as you can.

Restart PowerDNS afterwards.

Test it

curl -H 'X-API-Key: <your key>' http://127.0.0.1:8081/api/v1/servers/localhost

JSON in return means the API works. The built-in webserver listens on port 8081 and speaks plain HTTP.

Do not expose plain HTTP

An API key over plain HTTP is readable by anyone on the path. Put a TLS proxy such as nginx or Caddy in front of the webserver, and let it listen on 443. PowerDNS also suggests setting webserver-password as a second layer.

Connect it to DNSense

Add a connection, choose PowerDNS and fill in:

  • Host. Write it as https://dns.example.com when it sits behind a TLS proxy. Without a scheme, plain HTTP is assumed.
  • Port, optional. DNSense uses 8081 for HTTP and 443 for HTTPS when the field is empty.
  • API key, the value of api-key.

If the connection fails, check the firewall and webserver-allow-from first. They are the usual cause.