Deine Public-API-Aufrufe authentifizieren

Die CaptainDNS Public API authentifiziert Anfragen über einen API-Schlüssel im HTTP-Header Authorization. Kein OAuth, keine Session, keine Cookies. Dieses Handbuch erklärt Format, Lebenszyklus und Speicherpraktiken.

Den Schlüssel senden

POST /public/v1/resolve HTTP/1.1
Host: api.captaindns.com
Authorization: Bearer cdns_live_a3f2XK7mN9QrVtZ4yP1sH6eL8cF2dB5aR3gW7kJxM
Content-Type: application/json

{"qname":"captaindns.com","qtype":"A"}

Das Schema ist immer Bearer. Jedes andere Schema löst 401 INVALID_API_KEY aus. Schlüssel unterscheiden Groß- und Kleinschreibung.

Schlüsselformat

Ein Schlüssel besteht aus drei Segmenten:

cdns_<umgebung>_<36 alphanumerische Kleinbuchstaben>

Das im Dashboard angezeigte Präfix lautet cdns_<env>_ gefolgt von 8 Zeichen. Das vollständige Geheimnis wird niemals in der Datenbank gespeichert; CaptainDNS bewahrt nur seinen gepfefferten HMAC-SHA256-Hash auf.

Umgebungen

cdns_test_*-Schlüssel sind technisch identisch mit cdns_live_*-Schlüsseln: dieselben Endpunkte, dieselben Scopes, derselbe Credit-Verbrauch. Sie existieren, damit du in Logs und Dashboards zwischen Entwicklungs- und Produktions-Traffic unterscheiden kannst. Wir empfehlen, pro Umgebung (dev, staging, CI) einen Schlüssel anzulegen.

Scopes

Jeder Schlüssel trägt einen oder mehrere Scopes. Das Scope-Handbuch listet sie alle auf; kurz:

• dns:read: DNS-Auflösung, Propagation, DNSSEC, WHOIS für IPs.
• mail:read: SPF, DKIM, DMARC, BIMI, MTA-STS, TLS-RPT, DANE, Blacklist, SMTP, E-Mail-Header-Audit.
• mail:write: Deliverability-Score (derzeit der einzige Endpunkt hinter diesem Scope).
• web:read: URL-Checks, Page Crawl, Phishing-Erkennung.

Ein Aufruf auf einen Endpunkt, dessen Scope auf dem Schlüssel fehlt, liefert 403 INSUFFICIENT_SCOPE.

Rotation ohne Ausfallzeit

Einen kompromittierten oder veralteten Schlüssel tauscht man nicht einfach aus. Der unterstützte Ablauf ist die Rotation:

1. Im CaptainDNS-Dashboard löst du eine Rotation am betroffenen Schlüssel aus.
2. CaptainDNS erzeugt einen neuen Schlüssel mit denselben Scopes, Limits und derselben Umgebung.
3. Der alte Schlüssel bleibt 7 Tage gültig. In diesem Zeitraum können deine Dienste schrittweise migrieren.
4. Am Ende der Grace Period wird der alte Schlüssel automatisch widerrufen.

Denke daran, deinen Secrets-Manager vor Ablauf der Grace Period zu aktualisieren. Danach liefert jede Anfrage mit dem alten Schlüssel 401 REVOKED_API_KEY.

Sofortiger Widerruf

Wenn ein Schlüssel öffentlich leakt (Git-Repository, Log, ausgeschiedener Kollege), gibt es zwei Optionen:

• Aus dem Dashboard: Widerruf-Button am Schlüssel, Bestätigung mit einem Klick. Sofortige Wirkung, keine Grace Period.

Anfragen, die zum Zeitpunkt des Widerrufs bereits in Bearbeitung sind, werden abgeschlossen; neue Anfragen liefern 401 REVOKED_API_KEY.

IP-Allowlist

Die Pläne Business und Enterprise können einen Schlüssel auf eine CIDR-Liste beschränken. Die Prüfung erfolgt vor dem Handler, sodass die Anfrage keine Credits verbraucht, wenn die IP nicht zugelassen ist. Die Antwort lautet 403 IP_NOT_ALLOWED.

Beispiel eines Schlüssels, der auf die IPs deines GitHub-Actions-Workers und deines Produktions-Backends beschränkt ist:

{
  "ip_allowlist": [
    "4.175.114.0/23",
    "52.237.144.10/32"
  ]
}

Das Aktualisieren der Liste erfordert keine Rotation: bearbeite den Schlüssel im Dashboard, die neue Liste wird innerhalb einer Minute wirksam.

Best Practices für die Schlüsselspeicherung

• Secrets-Manager: 1Password, Doppler, AWS Secrets Manager, Vault. Niemals in eingecheckten .env-Dateien oder CI-YAML.
• Umgebungsvariable zur Laufzeit: injiziere den Schlüssel beim Prozessstart als Umgebungsvariable. Vermeide gemountete Klartext-Dateien.
• Periodische Rotation: 90 Tage für kritische Workloads, 180 Tage sonst. Plane eine Kalendererinnerung oder besser einen CI-Job.
• Kein Teilen im Team: ein Schlüssel pro Dienst, keinen Master-Schlüssel für das ganze SRE-Team teilen. Incident-Widerrufe werden chirurgisch.
• Minimale Scopes: wenn deine Integration nur DMARC-Checks durchführt, gib weder web:read noch mail:write. Reduziere den Blast Radius.

Auth-Probleme beheben

• 401 INVALID_API_KEY: fehlendes oder falsches Präfix, Schlüssel fehlt nach Bearer, manipuliertes Geheimnis. Prüfe, ob kein Leerzeichen oder Zeilenumbruch in den Client gelangt ist.
• 401 REVOKED_API_KEY: der Schlüssel wurde manuell oder automatisch widerrufen. Erzeuge einen neuen.
• 401 EXPIRED_API_KEY: du hast bei der Erstellung expires_at gesetzt und das Datum ist überschritten. Erzeuge einen neuen Schlüssel oder rotiere vorher.
• 403 IP_NOT_ALLOWED: deine Quell-IP ist nicht auf der Allowlist. Die Client-IP wird ausschließlich aus r.RemoteAddr abgeleitet. Wenn dein Traffic über einen Proxy läuft, schreibt CaptainDNS RemoteAddr vorab anhand von X-Forwarded-For nur dann um, wenn der unmittelbare Peer zur plattformseitig konfigurierten Liste vertrauenswürdiger Proxy-CIDRs gehört. Ein von einem beliebigen Client gesetztes X-Forwarded-For wird niemals berücksichtigt.
• 500 INTERNAL_ERROR: weist auf ein Problem bei CaptainDNS hin; öffne ein Support-Ticket mit der request_id.

Weiter geht es mit dem Scope-Handbuch oder mit dem Rate Limiting, wenn du einen Hochfrequenz-Client vorbereitest.