DNS API Documentation: PowerDNS-Compatible Automation

The Vortanix DNS API lets you manage DNS records in your zones programmatically—for Let’s Encrypt DNS-01 challenges, infrastructure automation, CI/CD pipelines and custom tooling.

The endpoint speaks the native PowerDNS HTTP API schema. Every PowerDNS-aware client (acme.sh, lego, certbot-dns-powerdns, cert-manager webhooks, …) talks to us without a Vortanix-specific plugin.

Tokens are created in the customer portal under Domains → API. Zones themselves are provisioned in the dashboard; the API manages records inside those zones.

Base URL & versioning

All customer DNS calls go to:

https://api.vortanix.com/api/v1

Host: api.vortanix.com · Prefix: /api/v1 · Stateless JSON (no session cookies, no CSRF).

Upstream reference: the official PowerDNS Authoritative HTTP API.

Authentication

Create a token in the portal (Domains → API → Create DNS API token). The plaintext secret is shown once—store it safely. You can scope a token to all of your zones or to specific zones only, and optionally set an expiry.

Headers

• Preferred (PowerDNS-native): X-API-Key: <token>
• Also accepted: Authorization: Bearer <token>

curl -s https://api.vortanix.com/api/v1/servers \
  -H "X-API-Key: YOUR_TOKEN"

Missing or invalid keys return HTTP 401 with a PowerDNS-shaped body: {"error":"…"}.

Server IDs

PowerDNS clients address a logical server. On the public API only these IDs are accepted:

• prodv1
• prodv2

Either ID works for automation; use one consistently in your tools (e.g. PDNS_ServerId=prodv1). Zone IDs are FQDNs with a trailing dot, for example example.com..

Endpoints

Base path below is relative to https://api.vortanix.com/api/v1.

Servers

• GET /servers — list public server aliases
• GET /servers/{server} — server descriptor (prodv1 or prodv2)

Zones

• GET /servers/{server}/zones — zones visible to your token (optional query ?zone=foo.bar.)
• GET /servers/{server}/zones/{zoneId} — full zone including RRsets
• PATCH /servers/{server}/zones/{zoneId} — create, replace or delete RRsets (see below)
• PUT /servers/{server}/zones/{zoneId}/notify — accepted for client compatibility (no-op success)
• PUT /servers/{server}/zones/{zoneId}/rectify — accepted for client compatibility (no-op success)

Not allowed via API

• POST …/zones — create zone → 403
• PUT …/zones/{zoneId} — replace zone metadata → 403
• DELETE …/zones/{zoneId} — delete zone → 403

Provision, rename or delete zones in the Vortanix dashboard only.

Changing records (PATCH)

Send a JSON body with a non-empty rrsets array. Each entry needs name, type and changetype (REPLACE or DELETE). Successful PATCH returns 204 No Content (PowerDNS behaviour).

curl -s -X PATCH \
  "https://api.vortanix.com/api/v1/servers/prodv1/zones/example.com." \
  -H "X-API-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rrsets": [{
      "name": "_acme-challenge.example.com.",
      "type": "TXT",
      "ttl": 60,
      "changetype": "REPLACE",
      "records": [{"content": "\"challenge-value\"", "disabled": false}]
    }]
  }'

Delete the same record:

curl -s -X PATCH \
  "https://api.vortanix.com/api/v1/servers/prodv1/zones/example.com." \
  -H "X-API-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rrsets": [{
      "name": "_acme-challenge.example.com.",
      "type": "TXT",
      "changetype": "DELETE"
    }]
  }'

Protected record types

• SOA — managed by Vortanix (403)
• Apex NS — apex nameservers only (403); NS under a subdomain is allowed
• DNSKEY / CDS / CDNSKEY — DNSSEC is platform-managed (403)
• RRset names must belong to the target zone

Client examples

acme.sh

export PDNS_Url="https://api.vortanix.com"
export PDNS_ServerId="prodv1"
export PDNS_Token="YOUR_TOKEN"
export PDNS_Ttl=60

acme.sh --issue --dns dns_pdns -d example.com -d '*.example.com' \
    --server letsencrypt

lego

export PDNS_API_URL="https://api.vortanix.com"
export PDNS_API_KEY="YOUR_TOKEN"
export PDNS_SERVER_NAME="prodv1"

lego --email you@example.com --dns pdns \
    --domains example.com --domains '*.example.com' \
    --accept-tos run

certbot (certbot-dns-powerdns)

# ~/.secrets/certbot/vortanix-pdns.ini
certbot_dns_powerdns:dns_powerdns_api_url = https://api.vortanix.com
certbot_dns_powerdns:dns_powerdns_api_key = YOUR_TOKEN

chmod 600 ~/.secrets/certbot/vortanix-pdns.ini

certbot certonly \
    --authenticator certbot-dns-powerdns:dns-powerdns \
    --certbot-dns-powerdns:dns-powerdns-credentials ~/.secrets/certbot/vortanix-pdns.ini \
    --certbot-dns-powerdns:dns-powerdns-propagation-seconds 30 \
    -d example.com -d "*.example.com"

cert-manager (webhook)

Install a PowerDNS webhook (e.g. zachomedia/cert-manager-webhook-pdns), then point it at Vortanix:

apiVersion: v1
kind: Secret
metadata:
  name: vortanix-pdns-api
  namespace: cert-manager
type: Opaque
stringData:
  api-key: YOUR_TOKEN
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-vortanix
spec:
  acme:
    email: you@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-vortanix-account
    solvers:
      - dns01:
          webhook:
            groupName: acme.zacharyseguin.ca
            solverName: pdns
            config:
              host: https://api.vortanix.com
              serverID: prodv1
              apiKeySecretRef:
                name: vortanix-pdns-api
                key: api-key

List zones with curl

TOKEN="YOUR_TOKEN"
BASE="https://api.vortanix.com/api/v1/servers/prodv1"

curl -s "$BASE/zones" -H "X-API-Key: $TOKEN" | jq '.[].name'

Errors & rate limits

Errors follow the PowerDNS shape:

{"error": "Human-readable message"}

• 401 — missing / invalid / expired API key
• 403 — operation or record type not allowed
• 404 — unknown server or zone outside token scope
• 422 — invalid PATCH body (e.g. empty rrsets)
• 429 — rate limit exceeded
• 502 — upstream DNS error

Rate limit: 600 requests per minute per client. Usage is logged for tokens you create (portal: token usage view).

Quick checklist

1. Create the zone in the Vortanix dashboard (and attach it to your company).
2. Mint an API token under Domains → API; prefer specific-zone scope for automation.
3. Point your tool at https://api.vortanix.com with server ID prodv1 or prodv2.
4. Send X-API-Key; use trailing-dot zone IDs (example.com.).
5. Do not try to create/delete zones or change SOA / apex NS / DNSSEC material via the API.

Need a hand wiring DNS-01 or scoping tokens? Contact our team. Related reading: glossary · blog home.