Scegliere gli scope adatti alla tua integrazione
Gli scope limitano cio 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 della 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 |
mail:read
| Endpoint | Crediti | Descrizione |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup è parsing SPF |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM per selector |
POST /public/v1/dmarc/lookup | 1 | Lookup è parsing DMARC |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI con recupero del logo |
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 |
mail:write
| Endpoint | Crediti | Descrizione |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score aggregato di DMARC, BIMI è reputazione |
Lo scope mail:write isola l'endpoint più costoso. Una chiave dedicata è consigliata.
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 |
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 è prod hanno ciascuno la propria chiave, distinte dal prefisso.
Chiave a scope unico per mail:write: separare lo scoring costoso previene 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 è poi il rate limiting.