Escolher os escopos adequados para sua integração
Os escopos restringem o que uma chave API pode fazer. Uma chave carrega um ou mais escopos; uma chamada a um endpoint cujo escopo não esta presente retorna 403 INSUFFICIENT_SCOPE. Aplique o principio do menor privilegio: conceda a cada chave apenas os escopos necessários para sua integração.
Escopos disponíveis
A V1 da API pública expoe quatro escopos:
| Escopo | Proposito | Uso tipico |
|---|---|---|
dns:read | Leitura de dados DNS | Watcher DNS, scripts de CI, ferramentas de troubleshooting |
mail:read | Diagnosticos de autenticação de email | Auditoria SPF/DKIM/DMARC, monitoramento de deliverability |
mail:write | Operacoes custosas de scoring de email | Deliverability score em pipeline |
web:read | Analise de página é URL | Detecção de phishing, verificação de links |
Nenhum escopo implica outro. mail:write não herda de mail:read.
Mapeamento completo de endpoints
dns:read
| Endpoint | Créditos | Descricao |
|---|---|---|
POST /public/v1/resolve | 1 | Resolução DNS padrao |
POST /public/v1/resolve/propagation | 3 | Teste de propagação multi-resolver |
POST /public/v1/dnssec/check | 3 | Verificação da cadeia DNSSEC |
POST /public/v1/ip/whois | 2 | WHOIS de um IP |
mail:read
| Endpoint | Créditos | Descricao |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup é parsing SPF |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM por selector |
POST /public/v1/dmarc/lookup | 1 | Lookup é parsing DMARC |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI com recuperacao do logo |
POST /public/v1/mta-sts/lookup | 2 | Lookup da policy MTA-STS |
POST /public/v1/tls-rpt/lookup | 2 | Lookup TLS-RPT |
POST /public/v1/dane/lookup | 2 | Lookup DANE/TLSA para SMTP |
POST /public/v1/blacklist/ip | 5 | Blacklist check multi-RBL |
POST /public/v1/smtp/check | 6 | Teste SMTP (HELO, STARTTLS, AUTH) |
POST /public/v1/mail/header-audit | 2 | Analise de header bruto de email |
mail:write
| Endpoint | Créditos | Descricao |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score agregado de DMARC, BIMI é reputacao |
O escopo mail:write isola o endpoint mais caro. Uma chave dedicada é recomendada.
web:read
| Endpoint | Créditos | Descricao |
|---|---|---|
POST /public/v1/url/check | 3 | Analise da cadeia de redirecionamentos |
POST /public/v1/page/crawl-check | 10 | Crawl de página com extracao de meta |
POST /public/v1/phishing/check | 8 | Detecção heuristica de phishing |
Estrategias de atribuicao
Chave unica com todos os escopos (fragil, não recomendado): útil para prototipar, perigoso em produção.
Uma chave por serviço (recomendado): cada microservico ou script tem sua propria chave com apenas os escopos necessários.
Uma chave por ambiente: dev, staging é produção tem cada um suas chaves, distinguidas pelo prefixo.
Chave com escopo unico para mail:write: separar o deliverability score do restante evita que um loop involuntario consuma toda a cota.
Adicionar ou remover um escopo
Os escopos sao fixados na criacao. Para modifica-los em uma chave existente:
- Crie uma nova chave com os escopos desejados.
- Implante-a no seu gerenciador de segredos.
- Revogue a chave antiga.
Ferramentas CaptainDNS relacionadas
Proximo passo: o modelo de créditos é depois o rate limiting.