DNS-API-Dokumentation: PowerDNS-kompatible Automation

Die Vortanix DNS-API ermöglicht die programmatische Verwaltung von DNS-Records in Ihren Zonen—für Let’s-Encrypt-DNS-01-Challenges, Infrastruktur-Automation, CI/CD und eigene Tools.

Der Endpunkt spricht das native Schema der PowerDNS HTTP API. Jeder PowerDNS-fähige Client (acme.sh, lego, certbot-dns-powerdns, cert-manager-Webhooks, …) spricht uns direkt an—ohne Vortanix-Plugin.

Tokens legen Sie im Kundenportal unter Domains → API an. Zonen werden im Dashboard provisioniert; die API verwaltet Records innerhalb dieser Zonen.

Basis-URL & Versionierung

Alle Kunden-DNS-Aufrufe gehen an:

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

Host: api.vortanix.com · Prefix: /api/v1 · zustandsloses JSON (keine Session-Cookies, kein CSRF).

Referenz: die offizielle PowerDNS Authoritative HTTP API.

Authentifizierung

Token im Portal anlegen (Domains → API → DNS-API-Token erstellen). Das Klartext-Secret wird einmalig angezeigt—sicher speichern. Scope: alle Ihre Zonen oder nur ausgewählte; optional mit Ablaufdatum.

Header

• Bevorzugt (PowerDNS-nativ): X-API-Key: <token>
• Ebenfalls akzeptiert: Authorization: Bearer <token>

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

Fehlende oder ungültige Keys liefern HTTP 401 mit PowerDNS-förmigem Body: {"error":"…"}.

Server-IDs

PowerDNS-Clients adressieren einen logischen Server. Auf der öffentlichen API sind nur diese IDs erlaubt:

• prodv1
• prodv2

Beide IDs eignen sich für Automation; in Ihren Tools konsistent verwenden (z. B. PDNS_ServerId=prodv1). Zone-IDs sind FQDNs mit trailing Dot, z. B. example.com..

Endpunkte

Pfade relativ zu https://api.vortanix.com/api/v1.

Server

• GET /servers — öffentliche Server-Aliase listen
• GET /servers/{server} — Server-Descriptor (prodv1 oder prodv2)

Zonen

• GET /servers/{server}/zones — für Ihren Token sichtbare Zonen (optional ?zone=foo.bar.)
• GET /servers/{server}/zones/{zoneId} — Zone inkl. RRsets
• PATCH /servers/{server}/zones/{zoneId} — RRsets anlegen, ersetzen oder löschen (siehe unten)
• PUT /servers/{server}/zones/{zoneId}/notify — für Client-Kompatibilität akzeptiert (No-Op mit Erfolg)
• PUT /servers/{server}/zones/{zoneId}/rectify — für Client-Kompatibilität akzeptiert (No-Op mit Erfolg)

Über die API nicht erlaubt

• POST …/zones — Zone anlegen → 403
• PUT …/zones/{zoneId} — Zonen-Metadaten ersetzen → 403
• DELETE …/zones/{zoneId} — Zone löschen → 403

Zonen anlegen, umbenennen oder löschen nur im Vortanix-Dashboard.

Records ändern (PATCH)

JSON-Body mit nicht-leerem rrsets-Array. Jeder Eintrag braucht name, type und changetype (REPLACE oder DELETE). Erfolgreiches PATCH liefert 204 No Content (PowerDNS-Verhalten).

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}]
    }]
  }'

Denselben Record wieder entfernen:

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"
    }]
  }'

Geschützte Record-Typen

• SOA — von Vortanix verwaltet (403)
• Apex-NS — nur Apex-Nameserver (403); NS unter einer Subdomain ist erlaubt
• DNSKEY / CDS / CDNSKEY — DNSSEC ist plattformseitig (403)
• RRset-Namen müssen zur Zielzone gehören

Client-Beispiele

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)

PowerDNS-Webhook installieren (z. B. zachomedia/cert-manager-webhook-pdns), dann auf Vortanix zeigen:

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

Zonen per curl listen

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

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

Fehler & Rate Limits

Fehler im PowerDNS-Format:

{"error": "Menschenlesbare Meldung"}

• 401 — API-Key fehlt / ungültig / abgelaufen
• 403 — Aktion oder Record-Typ nicht erlaubt
• 404 — unbekannter Server oder Zone außerhalb des Token-Scopes
• 422 — ungültiger PATCH-Body (z. B. leeres rrsets)
• 429 — Rate Limit überschritten
• 502 — Upstream-DNS-Fehler

Rate Limit: 600 Requests pro Minute pro Client. Die Nutzung Ihrer Tokens wird geloggt (Portal: Token-Usage-Ansicht).

Kurz-Checkliste

1. Zone im Vortanix-Dashboard anlegen (und der Company zuordnen).
2. API-Token unter Domains → API erzeugen; für Automation möglichst Zone-Scope wählen.
3. Tool auf https://api.vortanix.com mit Server-ID prodv1 oder prodv2 zeigen.
4. X-API-Key senden; Zone-IDs mit trailing Dot (example.com.).
5. Keine Zonen-Create/Delete und kein Ändern von SOA / Apex-NS / DNSSEC-Material über die API.

Hilfe bei DNS-01 oder Token-Scopes? Kontaktieren Sie uns. Weiterlesen: Glossar · Blog-Startseite.