Die passenden Scopes für deine Integration wählen
Scopes schränken ein, was ein API-Schlüssel darf. Ein Schlüssel trägt einen oder mehrere Scopes; ein Aufruf auf einen Endpunkt, dessen Scope nicht präsent ist, liefert 403 INSUFFICIENT_SCOPE. Wende das Prinzip der geringsten Berechtigung an: gib jedem Schlüssel nur die Scopes, die die jeweilige Integration benötigt.
Verfügbare Scopes
Die V1 der Public API stellt vier Scopes bereit:
| Scope | Zweck | Typische Nutzung |
|---|---|---|
dns:read | DNS-Daten lesen | DNS-Watcher, CI-Skripte, Troubleshooting-Tool |
mail:read | E-Mail-Authentifizierungsdiagnosen | SPF/DKIM/DMARC-Audit, Deliverability-Monitoring |
mail:write | Teure Operationen rund um E-Mail-Scoring | Deliverability-Score in einer Pipeline |
web:read | Seiten- und URL-Analyse | Phishing-Erkennung, Linkprüfung in einem Produkt |
Kein Scope impliziert einen anderen. mail:write erbt nicht von mail:read: wenn dein Schlüssel sowohl DMARC-Checks als auch Deliverability-Scoring macht, muss er beide Scopes tragen.
Vollständiges Endpunkt-Mapping
dns:read
| Endpunkt | Credits | Beschreibung |
|---|---|---|
POST /public/v1/resolve | 1 | Standard-DNS-Auflösung |
POST /public/v1/resolve/propagation | 3 | Propagationstest über mehrere Resolver |
POST /public/v1/dnssec/check | 3 | DNSSEC-Kettenprüfung |
POST /public/v1/ip/whois | 2 | WHOIS-Lookup für eine IP |
mail:read
| Endpunkt | Credits | Beschreibung |
|---|---|---|
POST /public/v1/spf/lookup | 1 | SPF-Lookup und Parsing |
POST /public/v1/dkim/lookup | 1 | DKIM-Lookup nach Selektor |
POST /public/v1/dmarc/lookup | 1 | DMARC-Lookup und Parsing |
POST /public/v1/bimi/lookup | 2 | BIMI-Lookup inklusive Logo |
POST /public/v1/mta-sts/lookup | 2 | MTA-STS-Policy-Lookup |
POST /public/v1/tls-rpt/lookup | 2 | TLS-RPT-Lookup |
POST /public/v1/dane/lookup | 2 | DANE/TLSA-Lookup für SMTP |
POST /public/v1/blacklist/ip | 5 | Blacklist-Check über mehrere RBLs |
POST /public/v1/smtp/check | 6 | SMTP-Test (HELO, STARTTLS, AUTH) |
POST /public/v1/mail/header-audit | 2 | Analyse eines rohen E-Mail-Headers |
mail:write
| Endpunkt | Credits | Beschreibung |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Aggregierter Score aus DMARC, BIMI und Reputation |
Der Scope mail:write isoliert den teuersten Endpunkt. Wir empfehlen einen dedizierten Schlüssel, wenn deine Integration ihn nutzt, um den Blast Radius im Leak-Fall zu reduzieren.
web:read
| Endpunkt | Credits | Beschreibung |
|---|---|---|
POST /public/v1/url/check | 3 | Analyse der Redirect-Kette |
POST /public/v1/page/crawl-check | 10 | Seiten-Crawl mit Metadaten-Extraktion |
POST /public/v1/phishing/check | 8 | Heuristische Phishing-Erkennung |
Hinweis: die 15 Endpunkte der text/*-Familie (Base64-Encoding, JSON/YAML-Konvertierung, Hash, Slug, Regex, Passwort usw.) sind ebenfalls dem Scope dns:read zugeordnet, um die Zuweisung zu vereinfachen. Sie führen keinerlei DNS-Auflösung durch. Die vollständige Liste findest du in der OpenAPI-Referenz.
Strategien der Scope-Zuweisung
Ein einziger Schlüssel für alle Scopes (fragil, nicht empfohlen): ein Geheimnis erhält Zugriff auf die gesamte API. Praktisch zum Prototyping, gefährlich in Produktion. Wechsle zu einer Multi-Schlüssel-Strategie, sobald die Integration stabil läuft.
Ein Schlüssel pro Dienst (empfohlen): jeder Microservice oder jedes Skript hat seinen eigenen Schlüssel, ausschließlich mit den benötigten Scopes. Bei einem Leak bleibt der Incident auf den betroffenen Bereich beschränkt.
Ein Schlüssel pro Umgebung: dev, staging und prod haben eigene Schlüssel, unterscheidbar durch das Präfix (cdns_test_* vs. cdns_live_*) und den Dashboard-Namen. Vereinfacht Dashboards und Alerts.
Ein Schlüssel mit einzelnem Scope für mail:write: die Trennung des Deliverability-Scores (30 Credits) vom Rest verhindert, dass eine ungewollte Schleife auf diesem einen Endpunkt dein Kontingent sprengt.
Einen Scope hinzufügen oder entfernen
Scopes sind nach der Erstellung des Schlüssels nicht mehr änderbar. So änderst du die Scopes eines bestehenden Schlüssels:
- Erstelle einen neuen Schlüssel mit den gewünschten Scopes.
- Rolle ihn in deinen Secrets-Manager aus.
- Widerrufe den alten Schlüssel.
Dieses Vorgehen verhindert, dass eine entfernte Berechtigung eine laufende Integration bricht.
Verwandte CaptainDNS-Tools
Die folgenden Web-Tools decken dieselben Diagnosen ab, hilfreich für die manuelle Prüfung:
Nächster Schritt: lies das Credit-Modell, um die monatlichen Kosten deiner Integration abzuschätzen, danach das Rate Limiting.