Ihre 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 Sie in Logs und Dashboards zwischen Entwicklungs- und Produktions-Traffic unterscheiden können. 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. Über das Dashboard oder the CaptainDNS dashboard lösen Sie eine Rotation 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 Ihre Dienste schrittweise migrieren.
4. Am Ende der Grace Period wird der alte Schlüssel automatisch widerrufen.

Aktualisieren Sie Ihren Secrets-Manager vor Ablauf der Grace Period. 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.
• Via the CaptainDNS dashboard: dieselbe Wirkung, praktisch für CI-Automatisierung.

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 keine Credits verbraucht werden, wenn die IP nicht zugelassen ist. Die Antwort lautet 403 IP_NOT_ALLOWED, mit der erkannten IP in details.

Beispiel eines Schlüssels, der auf GitHub-Actions-Runner und ein Backend beschränkt ist:

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

Das Aktualisieren der Liste erfordert keine Rotation: bearbeiten Sie 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: injizieren Sie den Schlüssel beim Prozessstart als Umgebungsvariable. Vermeiden Sie gemountete Klartext-Dateien.
• Periodische Rotation: 90 Tage für kritische Workloads, 180 Tage sonst. Planen Sie 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 Ihre Integration nur DMARC-Checks durchführt, gewähren Sie weder web:read noch mail:write. Reduzieren Sie den Blast Radius.

Leak-Erkennung

CaptainDNS nimmt am GitHub Secret Scanning Programm teil. Wenn Sie versehentlich einen Live-Schlüssel in ein öffentliches Repository pushen, wird das Muster cdns_live_* erkannt und der Owner benachrichtigt. Der Schlüssel wird automatisch widerrufen. Sie erhalten eine E-Mail mit dem fehlerhaften Commit-SHA und den nächsten Schritten.

Auth-Probleme beheben

• 401 INVALID_API_KEY: fehlendes oder falsches Präfix, Schlüssel fehlt nach Bearer, manipuliertes Geheimnis. Prüfen Sie, ob kein Leerzeichen oder Zeilenumbruch in den Client gelangt ist.
• 401 REVOKED_API_KEY: der Schlüssel wurde manuell oder automatisch widerrufen. Erzeugen Sie einen neuen.
• 401 EXPIRED_API_KEY: Sie haben bei der Erstellung expires_at gesetzt und das Datum ist überschritten. Erzeugen Sie einen neuen Schlüssel oder rotieren Sie vorher.
• 403 IP_NOT_ALLOWED: Ihre Quell-IP ist nicht auf der Allowlist. Prüfen Sie auch, ob X-Forwarded-For durch Ihren Proxy korrekt weitergereicht wird (private RFC1918-IPs werden ignoriert und der unmittelbare Hop verwendet).
• 500 INTERNAL_ERROR: weist auf ein Problem bei CaptainDNS hin; öffnen Sie ein Support-Ticket mit der request_id.

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