Skip to main content

Choose the right scopes for your integration

Scopes restrict what an API key can do. A key carries one or more scopes; a call to an endpoint whose scope is not present returns 403 INSUFFICIENT_SCOPE. Adopt least privilege: grant each key only the scopes required by the integration it serves.

Available scopes

The V1 public API exposes four scopes:

ScopeIntentTypical usage
dns:readRead DNS dataDNS watcher, CI scripts, troubleshooting tool
mail:readEmail authentication diagnosticsSPF/DKIM/DMARC audit, deliverability monitoring
mail:writeCostly email scoring operationsDeliverability score in a pipeline
web:readPage and URL analysisPhishing detection, link verification in a product

No scope implies another. mail:write does not inherit from mail:read: if your key needs both DMARC checks and deliverability scoring, it must carry both scopes.

Full endpoint mapping

dns:read

EndpointCreditsDescription
POST /public/v1/resolve1Standard DNS resolution
POST /public/v1/resolve/propagation3Multi-resolver propagation test
POST /public/v1/dnssec/check3DNSSEC chain validation
POST /public/v1/ip/whois2WHOIS lookup for an IP
POST /public/v1/ip/nslookup1Reverse DNS (PTR) lookup
POST /public/v1/ip/netmask1IPv4 netmask calculator
POST /public/v1/rdap/lookup2RDAP/WHOIS domain lookup
POST /public/v1/domain/dns-check5DNS server audit

mail:read

EndpointCreditsDescription
POST /public/v1/spf/lookup1SPF lookup and parsing
POST /public/v1/dkim/lookup1DKIM lookup by selector
POST /public/v1/dmarc/lookup1DMARC lookup and parsing
POST /public/v1/bimi/lookup2BIMI lookup with logo retrieval
POST /public/v1/mta-sts/lookup2MTA-STS policy lookup
POST /public/v1/tls-rpt/lookup2TLS-RPT lookup
POST /public/v1/dane/lookup2DANE/TLSA lookup for SMTP
POST /public/v1/blacklist/ip5Multi-RBL blacklist check
POST /public/v1/smtp/check6SMTP test (HELO, STARTTLS, AUTH)
POST /public/v1/mail/header-audit2Raw email header analysis
POST /public/v1/mail/header-analyze2Email header analysis
POST /public/v1/mail/domain-check10Full email domain readiness check
POST /public/v1/dmarcbis/check2DMARCbis Tree Walk analysis
POST /public/v1/dmarc/report/analyze5DMARC aggregate report analysis
POST /public/v1/certificates/csr/parse1CSR parser
POST /public/v1/certificats/bimi/parse1BIMI/VMC certificate parser
POST /public/v1/certificats/bimi/lookup2BIMI certificate download and parse

mail:write

EndpointCreditsDescription
POST /public/v1/deliverability/score30Aggregated DMARC, BIMI, reputation score
POST /public/v1/dmarc/generate1DMARC record generator
POST /public/v1/dmarcbis/migrate1DMARC to DMARCbis migration

The mail:write scope isolates modification endpoints. We recommend a dedicated key if your integration uses the deliverability score, to reduce the blast radius in case of a leak.

web:read

EndpointCreditsDescription
POST /public/v1/url/check3Redirect chain analysis
POST /public/v1/page/crawl-check10Page crawl with metadata extraction
POST /public/v1/phishing/check8Heuristic phishing detection

Allocation strategies

Single all-scopes key (fragile, not recommended): you give one secret the run of the whole API. Handy for prototyping, dangerous in production. Switch to a multi-key strategy as soon as the integration is stable.

One key per service (recommended): every microservice or script has its own key with only the scopes it needs. If a service leaks its key, the incident stays within its own blast radius.

One key per environment: dev, staging and prod each have their own keys, distinguished by prefix (cdns_test_* vs cdns_live_*) and by dashboard name. Simplifies consumption dashboards and alerting.

A single-scope key for mail:write: isolating the deliverability score (30 credits) from the rest prevents an accidental loop on that endpoint from wrecking your quota. The dedicated key can also carry a stricter client-side rate limit.

Adding or removing a scope

Scopes are fixed at key creation. To change the scopes of an existing key:

  1. Create a new key with the desired scopes.
  2. Deploy it to your secrets manager.
  3. Revoke the old key.

This procedure prevents a removed scope from breaking an in-flight integration. Large-scale scope migrations can also use the rotation with grace period when the overall structure stays the same.

The web tools below cover the same diagnostics; handy for manually verifying a surprising API result:

Next step: read the credit model to estimate your integration monthly cost, then read about rate limiting.