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:
| Scope | Intent | Typical usage |
|---|---|---|
dns:read | Read DNS data | DNS watcher, CI scripts, troubleshooting tool |
mail:read | Email authentication diagnostics | SPF/DKIM/DMARC audit, deliverability monitoring |
mail:write | Costly email scoring operations | Deliverability score in a pipeline |
web:read | Page and URL analysis | Phishing 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
| Endpoint | Credits | Description |
|---|---|---|
POST /public/v1/resolve | 1 | Standard DNS resolution |
POST /public/v1/resolve/propagation | 3 | Multi-resolver propagation test |
POST /public/v1/dnssec/check | 3 | DNSSEC chain validation |
POST /public/v1/ip/whois | 2 | WHOIS lookup for an IP |
POST /public/v1/ip/nslookup | 1 | Reverse DNS (PTR) lookup |
POST /public/v1/ip/netmask | 1 | IPv4 netmask calculator |
POST /public/v1/rdap/lookup | 2 | RDAP/WHOIS domain lookup |
POST /public/v1/domain/dns-check | 5 | DNS server audit |
mail:read
| Endpoint | Credits | Description |
|---|---|---|
POST /public/v1/spf/lookup | 1 | SPF lookup and parsing |
POST /public/v1/dkim/lookup | 1 | DKIM lookup by selector |
POST /public/v1/dmarc/lookup | 1 | DMARC lookup and parsing |
POST /public/v1/bimi/lookup | 2 | BIMI lookup with logo retrieval |
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 for SMTP |
POST /public/v1/blacklist/ip | 5 | Multi-RBL blacklist check |
POST /public/v1/smtp/check | 6 | SMTP test (HELO, STARTTLS, AUTH) |
POST /public/v1/mail/header-audit | 2 | Raw email header analysis |
POST /public/v1/mail/header-analyze | 2 | Email header analysis |
POST /public/v1/mail/domain-check | 10 | Full email domain readiness check |
POST /public/v1/dmarcbis/check | 2 | DMARCbis Tree Walk analysis |
POST /public/v1/dmarc/report/analyze | 5 | DMARC aggregate report analysis |
POST /public/v1/certificates/csr/parse | 1 | CSR parser |
POST /public/v1/certificats/bimi/parse | 1 | BIMI/VMC certificate parser |
POST /public/v1/certificats/bimi/lookup | 2 | BIMI certificate download and parse |
mail:write
| Endpoint | Credits | Description |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Aggregated DMARC, BIMI, reputation score |
POST /public/v1/dmarc/generate | 1 | DMARC record generator |
POST /public/v1/dmarcbis/migrate | 1 | DMARC 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
| Endpoint | Credits | Description |
|---|---|---|
POST /public/v1/url/check | 3 | Redirect chain analysis |
POST /public/v1/page/crawl-check | 10 | Page crawl with metadata extraction |
POST /public/v1/phishing/check | 8 | Heuristic 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:
- Create a new key with the desired scopes.
- Deploy it to your secrets manager.
- 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.
Related CaptainDNS tools
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.