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. Bei Schlüsseln wird zwischen Groß- und Kleinschreibung unterschieden.

Schlüsselformat

Ein Schlüssel besteht aus drei Segmenten:

cdns_<umgebung>_<36 alphanumerische Zeichen in Kleinschreibung>

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 mit einem Pepper versehenen 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, DMARC-Generator, Migration von DMARC zu DMARCbis, erzwungene Neuauflösung eines Hosted-SPF-Profils.
• 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ösen Sie 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 Ihre Dienste schrittweise migrieren.
4. Am Ende der Grace Period wird der alte Schlüssel automatisch widerrufen.

Denken Sie daran, Ihren 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), erfolgt der Widerruf im Dashboard: Widerruf-Button am Schlüssel, dann 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 Ihres GitHub-Actions-Workers und Ihres Produktions-Backends 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. Ein Widerruf im Incident-Fall bleibt so chirurgisch genau.
• Minimale Scopes: wenn Ihre Integration nur DMARC-Checks durchführt, geben Sie weder web:read noch mail:write. Reduzieren Sie den Blast Radius.

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 ihn vorher.
• 403 IP_NOT_ALLOWED: Ihre Quell-IP ist nicht auf der Allowlist. Die Client-IP wird ausschließlich aus r.RemoteAddr abgeleitet. Wenn Ihr 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; ö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.