API und Automatisierung

Die Oberfläche benutzt dieselbe HTTP-API, die auch der Automatisierung offensteht. Basis-Pfad ist /api/v1.

Authentifizierung

Zwei Wege führen hinein:

Session-Cookie — der Weg der Oberfläche (POST /api/v1/auth/login).

API-Key als Bearer-Token — der Weg für Skripte und CI:

curl -H "Authorization: Bearer dnse_…" https://dns.example.com/api/v1/zones

API-Keys

Art	Reichweite
Projekt-Key	ein Projekt, mit einer Projektrolle (z. B. Editor)
Admin-Key	instanzweit, eingeschränkt durch Scopes

Admin-Scopes sind users, teams, projects und settings. Ein Admin-Key ohne projects kommt an keine Projektdaten.

Keys werden einmalig beim Anlegen angezeigt; gespeichert wird nur ein Hash. Ein Ablaufdatum ist möglich — 14 Tage vorher erinnert eine Mail an die Administratoren, denn Keys erneuern sich nicht von selbst.

Anlegen: Projekt → Management → API-Keys (Projekt-Key) bzw. Administration → API-Keys (Admin-Key).

Durchstich: vom leeren System zur verwalteten Zone

Der komplette Weg per curl — mit einem Projekt-Key mit Editor-Rolle:

H='Authorization: Bearer dnse_IhrKeyHier'
BASE=https://dns.example.com/api/v1

1. Provider-Account registrieren (Beispiel Hetzner, ein API-Token):

curl -s -X POST "$BASE/accounts/register" -H "$H" \
  -H "Content-Type: application/json" \
  -d '{
        "projectId": "01…",
        "provider": "hetzner",
        "name": "Hetzner Produktion",
        "credentials": { "api_token": "…" }
      }'
# → 201 {"id":"01…","status":"ok",…}

Welche Credential-Felder ein Anbieter erwartet, sagt GET /api/v1/providers — jede Integration beschreibt ihre Felder selbst.

2. Zonen des Accounts ansehen (Onboarding-Liste):

curl -s "$BASE/accounts/<accountId>/zones" -H "$H"
# → [{"name":"example.com"},{"name":"example.org"}]

3. Zone übernehmen:

curl -s -X POST "$BASE/zones/adopt" -H "$H" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "<accountId>", "zone": "example.com"}'
# → 201 {"id":"<zoneId>",…}

4. Record Set schreiben — ersetzt das ganze Set aus Name und Typ:

curl -s -X POST "$BASE/zones/<zoneId>/record-sets/upsert" -H "$H" \
  -H "Content-Type: application/json" \
  -d '{"name": "www", "type": "A", "ttl": 300,
       "records": ["203.0.113.10", "203.0.113.11"]}'

5. Drift prüfen und auflösen:

curl -s "$BASE/zones/<zoneId>/drift" -H "$H"
# → [{"id":"<driftId>","kind":"MODIFIED","name":"www","type":"A",…}]

curl -s -X POST "$BASE/drift/<driftId>/resolve" -H "$H" \
  -H "Content-Type: application/json" \
  -d '{"action": "enforce"}'          # oder "adopt" / "ignore"

6. Providerübergreifend suchen:

curl -s "$BASE/inventory/search?q=203.0.113.10&type=A" -H "$H"
# → {"hits":[…],"truncated":false}

Weitere häufige Aufrufe

Zweck	Aufruf
Instanz-Info (öffentlich, ohne Auth)	`GET /api/v1/instance`
Zertifikat anfordern	`POST /api/v1/projects/{id}/certificates/request`
Zertifikat herunterladen	`GET /api/v1/certificates/{id}/download`
Provider-Umzug starten	`POST /api/v1/zones/{id}/migrate`
Migrationen eines Projekts	`GET /api/v1/projects/{id}/migrations`
DynDNS-Update (Router)	`GET /nic/update` (Basic Auth mit Token)
DynDNS-Update (Skript)	`POST /api/v1/dyndns/update` (Bearer)

Die vollständige Liste mit allen Parametern und Schemas steht in der generierten API-Referenz (Seitenleiste → DNS-Editor API). Neben der im Repo gepflegten Spezifikation (api/openapi.yaml) liefert jede Instanz unter /api/v1/openapi.json die zur Laufzeit erzeugte Fassung.

Fehlerverhalten

Fehler kommen als JSON mit error-Feld und passendem Status:

Status	Bedeutung
`400`	ungültige Eingabe
`401`	keine gültige Anmeldung
`403`	Rolle oder Scope reicht nicht
`404`	existiert nicht oder liegt außerhalb der eigenen Reichweite
`409`	Konflikt (z. B. Zone bereits verwaltet)

Dass „fremd” und „nicht vorhanden” gleich aussehen, ist Absicht: Die API verrät nicht, was es außerhalb der eigenen Rechte gibt.