Scegliere gli scope adatti alla tua integrazione
Gli scope limitano ciò che una chiave API può fare. Una chiave porta uno o più scope; una chiamata a un endpoint con scope mancante restituisce 403 INSUFFICIENT_SCOPE. Applica il principio del minimo privilegio: assegna a ciascuna chiave solo gli scope richiesti dall'integrazione.
Scope disponibili
La V1 dell'API pubblica espone quattro scope:
| Scope | Scopo | Uso tipico |
|---|---|---|
dns:read | Lettura di dati DNS | Watcher DNS, script CI, strumenti di troubleshooting |
mail:read | Diagnosi di autenticazione email | Audit SPF/DKIM/DMARC, monitoraggio deliverability |
mail:write | Operazioni onerose legate allo scoring email | Deliverability score in pipeline |
web:read | Analisi di pagine e URL | Rilevamento phishing, verifica di link |
Nessuno scope implica un altro. mail:write non eredita da mail:read.
Mapping completo degli endpoint
dns:read
| Endpoint | Crediti | Descrizione |
|---|---|---|
POST /public/v1/resolve | 1 | Risoluzione DNS standard |
POST /public/v1/resolve/propagation | 3 | Test di propagazione multi-resolver |
POST /public/v1/dnssec/check | 3 | Verifica della catena DNSSEC |
POST /public/v1/ip/whois | 2 | WHOIS di un indirizzo IP |
POST /public/v1/ip/nslookup | 1 | Reverse DNS (PTR) |
POST /public/v1/ip/netmask | 1 | Calcolatore di maschera IPv4 |
POST /public/v1/rdap/lookup | 2 | RDAP/WHOIS di dominio |
POST /public/v1/domain/dns-check | 5 | Audit dei server DNS |
mail:read
| Endpoint | Crediti | Descrizione |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup e parsing SPF |
POST /public/v1/spf/validate | 1 | Validazione SPF (senza lookup DNS) |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM per selector |
POST /public/v1/dkim/validate | 1 | Validazione DKIM (senza lookup DNS) |
POST /public/v1/dmarc/lookup | 1 | Lookup e parsing DMARC |
POST /public/v1/dmarc/validate | 1 | Validazione DMARC (senza lookup DNS) |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI con recupero del logo |
POST /public/v1/bimi/validate | 2 | Validazione BIMI (senza lookup DNS) |
POST /public/v1/bimi/logo/lookup | 2 | Download e validazione di logo BIMI |
POST /public/v1/mta-sts/lookup | 2 | Lookup della policy MTA-STS |
POST /public/v1/tls-rpt/lookup | 2 | Lookup TLS-RPT |
POST /public/v1/dane/lookup | 2 | Lookup DANE/TLSA per SMTP |
POST /public/v1/blacklist/ip | 5 | Blacklist check multi-RBL |
POST /public/v1/smtp/check | 6 | Test SMTP (HELO, STARTTLS, AUTH) |
POST /public/v1/mail/header-audit | 2 | Analisi di header grezzo di email |
POST /public/v1/mail/header-analyze | 2 | Analisi di header email |
POST /public/v1/mail/domain-check | 10 | Audit completo di dominio email |
POST /public/v1/dmarcbis/check | 2 | Analisi DMARCbis Tree Walk |
POST /public/v1/dmarc/report/analyze | 5 | Analisi di report DMARC aggregato |
POST /public/v1/certificats/bimi/parse | 1 | Parsing di certificato BIMI/VMC |
POST /public/v1/certificats/bimi/lookup | 2 | Download e parsing di certificato BIMI |
GET /public/v1/spf/hosted | 1 | Elenco dei profili SPF ospitati della chiave |
GET /public/v1/spf/hosted/{id} | 1 | Dettaglio di un profilo SPF ospitato |
GET /public/v1/spf/hosted/{id}/history | 2 | Storico di risoluzione di un profilo (paginato) |
GET /public/v1/spf/hosted/{id}/stats | 2 | Statistiche di un profilo (24 ore, 7 giorni, 30 giorni) |
mail:write
| Endpoint | Crediti | Descrizione |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score aggregato di DMARC, BIMI e reputazione |
POST /public/v1/dmarc/generate | 1 | Generatore di record DMARC |
POST /public/v1/dmarcbis/migrate | 1 | Migrazione da DMARC a DMARCbis |
POST /public/v1/spf/hosted/{id}/resolve | 5 | Ri-risoluzione forzata di un profilo SPF ospitato |
Lo scope mail:write isola gli endpoint di modifica. Se la tua integrazione usa lo score di recapitabilità, è consigliabile creare una chiave dedicata per ridurre l'impatto in caso di fuga.
web:read
| Endpoint | Crediti | Descrizione |
|---|---|---|
POST /public/v1/url/check | 3 | Analisi della catena di redirect |
POST /public/v1/page/crawl-check | 10 | Crawl di pagina con estrazione di meta |
POST /public/v1/phishing/check | 8 | Rilevamento euristico di phishing |
POST /public/v1/http/headers-check | 2 | Header HTTP, catena di redirect, TLS |
POST /public/v1/http/hsts-check | 3 | Analisi HSTS e idoneità al preload |
POST /public/v1/certificates/ssl/check | 2 | Certificato TLS di un server web e la sua catena |
POST /public/v1/certificates/csr/parse | 2 | Analisi di conformità di un CSR |
Transizione di scope su /certificates/csr/parse. Questo endpoint apparteneva alla famiglia mail:read e costava 1 credito. Poiché un CSR non ha nulla di specificamente mail, il suo scope di destinazione è ora web:read e il suo costo è di 2 crediti. Per non rompere nessuna chiave già emessa, mail:read resta accettato durante un periodo di transizione, ma sarà rimosso: crea le nuove chiavi con web:read e aggiungi web:read alle chiavi esistenti che chiamano questo endpoint.
Nota: i 15 endpoint della famiglia text/* (encoding base64, conversione JSON/YAML, hash, slug, regex, password, ecc.) sono anch'essi collegati allo scope dns:read per semplificare l'assegnazione. Non effettuano alcuna risoluzione DNS. Consulta il riferimento OpenAPI per l'elenco completo.
Strategie di assegnazione
Una sola chiave con tutti gli scope (fragile, sconsigliato): comodo per prototipare, pericoloso in produzione.
Una chiave per servizio (consigliato): ogni microservizio o script ha la sua chiave con solo gli scope necessari.
Una chiave per ambiente: dev, staging e prod hanno ciascuno la propria chiave, distinte dal prefisso.
Chiave a scope unico per mail:write: separare lo scoring costoso evita che un ciclo involontario prosciughi la quota.
Aggiungere o rimuovere uno scope
Gli scope sono fissati alla creazione. Per modificarli su una chiave esistente:
- Crea una nuova chiave con gli scope desiderati.
- Distribuiscila nel tuo gestore di segreti.
- Revoca la vecchia chiave.
Strumenti CaptainDNS correlati
Prossimo passo: il modello di crediti e poi il rate limiting.