Die passenden Scopes für Ihre 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. Wenden Sie das Prinzip der geringsten Berechtigung an: geben Sie 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 Ihr 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 Ihre 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

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. Wechseln Sie 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 Ihr Kontingent sprengt.

Einen Scope hinzufügen oder entfernen

Scopes sind nach der Erstellung des Schlüssels nicht mehr änderbar. So ändern Sie die Scopes eines bestehenden Schlüssels:

Erstellen Sie einen neuen Schlüssel mit den gewünschten Scopes.
Rollen Sie ihn in Ihren Secrets-Manager aus.
Widerrufen Sie den alten Schlüssel.

Dieses Vorgehen verhindert, dass eine entfernte Berechtigung eine laufende Integration bricht.