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 está presente retorna 403 INSUFFICIENT_SCOPE. Aplique o princípio do menor privilégio: conceda a cada chave apenas os escopos necessários para sua integração.
Escopos disponíveis
A V1 da API pública expõe quatro escopos:
| Escopo | Propósito | Uso típico |
|---|---|---|
dns:read | Leitura de dados DNS | Watcher DNS, scripts de CI, ferramentas de troubleshooting |
mail:read | Diagnósticos de autenticação de email | Auditoria SPF/DKIM/DMARC, monitoramento de deliverability |
mail:write | Operações custosas de scoring de email | Deliverability score em pipeline |
web:read | Análise de página e 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 | Descrição |
|---|---|---|
POST /public/v1/resolve | 1 | Resolução DNS padrão |
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 |
POST /public/v1/ip/nslookup | 1 | DNS reverso (PTR) |
POST /public/v1/ip/netmask | 1 | Calculadora de máscara IPv4 |
POST /public/v1/rdap/lookup | 2 | RDAP/WHOIS de domínio |
POST /public/v1/domain/dns-check | 5 | Auditoria de servidores DNS |
mail:read
| Endpoint | Créditos | Descrição |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup e parsing SPF |
POST /public/v1/spf/validate | 1 | Validação SPF (sem lookup DNS) |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM por seletor |
POST /public/v1/dkim/validate | 1 | Validação DKIM (sem lookup DNS) |
POST /public/v1/dmarc/lookup | 1 | Lookup e parsing DMARC |
POST /public/v1/dmarc/validate | 1 | Validação DMARC (sem lookup DNS) |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI com recuperação do logo |
POST /public/v1/bimi/validate | 2 | Validação BIMI (sem lookup DNS) |
POST /public/v1/bimi/logo/lookup | 2 | Download e validação do logotipo BIMI |
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 | Análise de header bruto de email |
POST /public/v1/mail/header-analyze | 2 | Análise de cabeçalhos de email |
POST /public/v1/mail/domain-check | 10 | Auditoria completa de domínio de email |
POST /public/v1/dmarcbis/check | 2 | Análise DMARCbis Tree Walk |
POST /public/v1/dmarc/report/analyze | 5 | Análise de relatório DMARC agregado |
POST /public/v1/certificats/bimi/parse | 1 | Parsing de certificado BIMI/VMC |
POST /public/v1/certificats/bimi/lookup | 2 | Download e parsing de certificado BIMI |
GET /public/v1/spf/hosted | 1 | Lista dos perfis SPF hospedados da chave |
GET /public/v1/spf/hosted/{id} | 1 | Detalhe de um perfil SPF hospedado |
GET /public/v1/spf/hosted/{id}/history | 2 | Histórico de resolução de um perfil (paginado) |
GET /public/v1/spf/hosted/{id}/stats | 2 | Estatísticas de um perfil (24 horas, 7 dias, 30 dias) |
mail:write
| Endpoint | Créditos | Descrição |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score agregado de DMARC, BIMI e reputação |
POST /public/v1/dmarc/generate | 1 | Gerador de registro DMARC |
POST /public/v1/dmarcbis/migrate | 1 | Migração de DMARC para DMARCbis |
POST /public/v1/spf/hosted/{id}/resolve | 5 | Re-resolução forçada de um perfil SPF hospedado |
O escopo mail:write isola os endpoints de escrita. Uma chave dedicada é recomendada se sua integração usar o score de entregabilidade, para reduzir o impacto em caso de vazamento.
web:read
| Endpoint | Créditos | Descrição |
|---|---|---|
POST /public/v1/url/check | 3 | Análise da cadeia de redirecionamentos |
POST /public/v1/page/crawl-check | 10 | Crawl de página com extração de meta |
POST /public/v1/phishing/check | 8 | Detecção heurística de phishing |
POST /public/v1/http/headers-check | 2 | Cabeçalhos HTTP, cadeia de redirecionamentos, TLS |
POST /public/v1/http/hsts-check | 3 | Análise HSTS e elegibilidade para preload |
POST /public/v1/certificates/ssl/check | 2 | Certificado TLS de um servidor web e sua cadeia |
POST /public/v1/certificates/csr/parse | 2 | Análise de conformidade de um CSR |
Transição de escopo em /certificates/csr/parse. Este endpoint pertencia à família mail:read e custava 1 crédito. Como um CSR não tem nada especificamente de mail, seu escopo-alvo passa a ser web:read e seu custo é de 2 créditos. Para não quebrar nenhuma chave já emitida, mail:read continua sendo aceito durante um período de transição, mas será retirado: crie suas novas chaves com web:read e adicione web:read às chaves existentes que chamam este endpoint.
Nota: os 15 endpoints da família text/* (encoding base64, conversão JSON/YAML, hash, slug, regex, password, etc.) também estão vinculados ao escopo dns:read para simplificar a atribuição. Eles não efetuam nenhuma resolução DNS. Consulte a referência OpenAPI para a lista completa.
Estratégias de atribuição
Chave única com todos os escopos (frágil, não recomendado): útil para prototipar, perigoso em produção.
Uma chave por serviço (recomendado): cada microsserviço ou script tem sua própria chave com apenas os escopos necessários.
Uma chave por ambiente: dev, staging e produção têm cada um suas próprias chaves, distinguidas pelo prefixo.
Chave com escopo único para mail:write: separar o deliverability score do restante evita que um loop involuntário consuma toda a cota.
Adicionar ou remover um escopo
Os escopos são fixados na criação. Para modificá-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
Próximo passo: o modelo de créditos e depois o rate limiting.