API overview

Everything the dashboard does goes through DNZ’s HTTP API under /api. The CLI uses the same API. For automation (Terraform, scripts, CI, ACME DNS-01 certificates), use an API token.

API tokens

Creating a token

Dashboard
CLI

Go to Settings → API tokens → Create token. This needs the Manage API tokens permission (tokens.manage), which the Owner role has.

dnz token create certbot -p records.write,zones.read -z example.com --expires-in-days 90

See API tokens in the CLI reference.

A token has:

A division. It can only reach zones in the division it was created in.
Permissions: any of zones.read, records.write, zones.write and logs.read.
Zones: every zone in the division, or only some. A token limited to some zones can’t create new zones.
An expiry: 30 days, 90 days, 1 year, or never.

The token (dnz_…) is shown once, when it is created. DNZ only stores its hash. If you lose it, revoke it and create a new one.

A token never has more rights than its creator

You can only give a token permissions you have yourself in that division. The rights are checked again every time the token is used, so when the creator loses a right, the token loses it too. Every change made with a token appears in the audit log as <creator> via <token name>.

What a token can reach

Tokens can only call the zone, record, query log and ACME endpoints, the Dynamic DNS endpoint, and pushing a DHCP server’s lease file and reading leases and IPAM (DHCP). Account, user, role and settings endpoints always need a normal sign-in.

Permission	Lets the token
`zones.read`	List zones, read records, tags and zone files, refresh secondary zones
`zones.write`	Create, change and delete zones
`records.write`	Create, change and delete records, ACME challenges and Dynamic DNS
`logs.read`	Read the query log of the division’s zones

Authentication

Send the token as a Bearer token:

curl -H "Authorization: Bearer dnz_…" https://dns.example.com/api/token

HTTP Basic works too, with the token as the password and any username. This is what lego and Traefik use:

curl -u "any:dnz_…" https://dns.example.com/api/token

GET /api/token answers with the token’s name, division, permissions and the zones it can reach, which makes it a handy check in scripts. See Token info.

Errors

Errors come back as JSON with an HTTP status:

{ "error": "…" }

Status	Meaning
`400`	The request is invalid: a bad value, a field missing, an id outside the zone
`401`	No valid token or session
`403`	The token or user lacks the permission
`404`	The zone or record doesn’t exist
`409`	A conflict: a duplicate record, a CNAME next to other data

Example: adding a record

curl -X POST https://dns.example.com/api/zones/3/records \
  -H "Authorization: Bearer $DNZ_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"app","type":"A","value":"192.0.2.20","ttl":300}'

Find a zone’s id with GET /api/divisions/{id}/zones, or with dnz --json zone list.

There is no DNZ Terraform provider yet. A generic REST provider works with these endpoints; see Terraform.

Endpoints

Zones

List, create, change, delete, export and refresh zones; the query log; token info.

Records

The record format, filtering and bulk changes.

ACME and Dynamic DNS

DNS-01 challenges for lego, Traefik and certbot; DynDNS2 for routers.

Filtering

Blocklists, rules, client groups, schedules, safe search and response policy zones.

DHCP and IPAM

DHCP servers, lease file pushes, leases, subnets and conflicts.

Settings

Response rate limiting and the GeoIP database.

Proxy

Proxies, routers, services and middlewares.

​API tokens

​Creating a token

​A token never has more rights than its creator

​What a token can reach

​Authentication

​Errors

​Example: adding a record

​Endpoints

Zones

Records

ACME and Dynamic DNS

Filtering

DHCP and IPAM

Settings

Proxy

API tokens

Creating a token

A token never has more rights than its creator

What a token can reach

Authentication

Errors

Example: adding a record

Endpoints