CNF API · v1

Übersicht

Version 1 stellt DNS-Vorgänge für Zonen bereit, die Sie über die DNS-Verwaltung zugeordnet haben. Tokens können Sie unter Konto → API-Schlüssel erstellen und widerrufen.

Basis-URL und Versionierung

https://api.c.nf/v1

Alle Endpunkte liegen unter /v1. Inkompatible Änderungen erhalten einen neuen Pfad für die Hauptversion. Abwärtskompatible Felder und Endpunkte können zu v1 hinzugefügt werden und werden im Änderungsprotokoll festgehalten.

Authentifizierung und Scopes

Jede Anfrage, die Kontodaten liest oder ändert, muss ein Bearer-Token enthalten. Tokens beginnen mit cnf_, gefolgt von 32 Hexadezimalzeichen.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Tokens werden als nicht umkehrbare Hashwerte gespeichert; der vollständige Wert wird nur bei der Erstellung angezeigt. Wenn ein Token verloren geht, widerrufen Sie es und erstellen Sie ein neues.

Jedes Token besitzt Scopes. Ein Token ohne konfigurierten Scope erhält standardmäßig dns:read. Der Schreib-Scope erlaubt auch Lesezugriffe.

Bei einer Abweichung wird 403 forbidden_scope zurückgegeben; zur Diagnose sind sowohl required_scopes als auch token_scopes enthalten.

Trennung nach Benutzer

Ein Bearer-Token wird genau einer user_id zugeordnet. Jeder Zonenhandler prüft vor jedem Lese- oder Schreibzugriff die bestätigte Zuordnung dieses Benutzers. Es gibt keine Administratorausnahme, keinen Identitätswechselpfad und keine Umgehung zwischen Benutzern.

Auch ein Token mit * kann nur auf Zonen zugreifen, die vom eigenen Benutzer bestätigt wurden. Beim Zugriff auf die Zone eines anderen Kontos wird 403 forbidden_zone zurückgegeben.

Antwortumschlag

Erfolgreiche Antwort

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

Fehlerantwort

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id ist in jeder Antwort enthalten und kann gefahrlos in clientseitigen Protokollen aufgezeichnet werden.

Fehlercodes

Zonenbestätigung

Wenn POST /v1/dns/zones eine Zone zuordnet, wählt der Server einen der folgenden Wege:

1. Sofortige Bestätigung (method: "auto") — Wird verwendet, wenn kein anderes Konto die Zone zugeordnet hat. Die Zuordnung wird sofort bestätigt. Einträge werden erst autoritativ, nachdem der Eigentümer die NS-Delegierung beim Registrar auf die zurückgegebenen Nameserver verweist.
2. TXT-Bestätigung — Wird bei einer konkurrierenden Zuordnung verwendet. Fügen Sie den zurückgegebenen TXT-Wert unter _cnfdns-verify.<zone> hinzu und rufen Sie anschließend POST /v1/dns/zones/{zone}/verify auf.
3. Alte NS-Bestätigung — Ältere ausstehende Zuordnungen können verify_method: "ns" verwenden. Bei der Bestätigung werden die aktiven NS-Antworten der Zone mit dem erwarteten Nameserversatz verglichen.

Die Bestätigung ist idempotent. Bei einer Wiederholung für eine bestätigte Zuordnung wird verified: true zurückgegeben, ohne die Zuordnung zu ändern.

Eintragstypen und Grenzwerte

Unterstützte Eintragstypen

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority ist für MX und SRV erforderlich und wird bei anderen Typen ignoriert. ttl muss zwischen 60 und 2.592.000 Sekunden liegen.

Endpunkte

Öffentliche Dienste

Kleine, verlässliche Endpunkte ohne Konto: Zeit, Adresse, Land, Wechselkurse und Hashes.

Konto

Zu wem ein Token gehört und was es darf.

DNS

Eine Domain beanspruchen, die Kontrolle nachweisen und dann ihre Einträge verwalten.

Zugangsdaten

Der private Zugangsdatenspeicher hinter dem Zugangsdaten-Werkzeug.

Dateien

Persönlicher Dateispeicher: auflisten, hochladen, bearbeiten, teilen und löschen.

CDN

Edge-Caching und Datenverkehr für Ihre geteilten Dateien.

SMS-Weiterleitung

Vom Telefon weitergeleitete Nachrichten und die Schlüssel dafür.

Statische Websites

ZIP hochladen, Website ausliefern.

Deployments

Ihre bereitgestellten Formular-, Webhook- und Kurzlink-Endpunkte.

Domains

Ihr Domain-Portfolio und dessen Registrierungsdaten.

Pakete

Releases veröffentlichen und deren Versionen und Downloadzahlen abrufen.

WHOIS

Registrierungsdaten einer Domain, zwischengespeichert und mit den Domain-Werkzeugen geteilt.

Für KI-Agenten

Verweisen Sie einen Agenten auf /v1/ai — eine Kurzanleitung, die direkt in einen Prompt passt — oder auf /v1/ai?format=json für dieselben Endpunkte als Werkzeugdefinitionen. /v1/openapi.json ist der vollständige OpenAPI-3.1-Vertrag, /llms.txt die Karte für Crawler. Alle vier entstehen aus derselben Routentabelle wie diese Seite und können daher keinen Endpunkt beschreiben, den es nicht gibt.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

Anfragefelder

Zonenzuordnung erstellen

DNS-Eintrag erstellen

DNS-Eintrag aktualisieren

Beispiele

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

Schnellstart

1. Erstellen Sie einen API-Schlüssel mit dns:write unter Konto → API-Schlüssel und kopieren Sie ihn bei der Anzeige.
2. Speichern Sie das Token in einer geschützten Umgebungsvariable auf Ihrem Rechner.
3. Rufen Sie GET /v1/account/me auf, um das Token und seine Scopes zu bestätigen.
4. Ordnen Sie eine Zone zu. Die Antwort gibt an, ob die Bestätigung sofort, TXT-basiert oder mit der alten NS-Methode erfolgt.
5. Erbringen Sie gegebenenfalls den zurückgegebenen DNS-Nachweis und rufen Sie anschließend den Bestätigungsendpunkt auf.
6. Erstellen, lesen, aktualisieren oder löschen Sie Einträge erst, nachdem die Zuordnung bestätigt wurde.

Änderungsprotokoll

v1.1.0 — Zonenverwaltung

• API-basierte Zonenzuordnungen einschließlich sofortiger und TXT-basierter Bestätigungswege hinzugefügt.
• Endpunkte für den Status einzelner Zonen und die idempotente Bestätigung hinzugefügt.
• Widerruf von Zuordnungen ohne implizites Löschen von Einträgen hinzugefügt.
• Filter für bestätigte, ausstehende und alle Zuordnungen zur Zonenliste hinzugefügt.

v1.0.0 — Erstveröffentlichung

• Bearer-Token-Authentifizierung und Trennung der Zonen nach Benutzer hinzugefügt.
• Lese- und Schreib-Scopes hinzugefügt.
• Endpunkte für Konto, Zonenliste und Eintragsverwaltung hinzugefügt.
• Einheitlichen Antwortumschlag mit Anfragekennung hinzugefügt.