Escolher os escopos adequados para a 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 a 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, monitorização de deliverability |
mail:write | Operações custosas de scoring de email | Deliverability score em pipeline |
web:read | Análise de página e URL | Deteçã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 inverso (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 selector |
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 | Descarregamento e validação do logótipo 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 headers 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 | Descarregamento e parsing de certificado BIMI |
GET /public/v1/spf/hosted | 1 | Lista dos perfis SPF alojados da chave |
GET /public/v1/spf/hosted/{id} | 1 | Detalhe de um perfil SPF alojado |
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 registo 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 alojado |
O escopo mail:write isola os endpoints de escrita. É recomendada uma chave dedicada se a sua integração usar o score de entregabilidade, para reduzir o impacto em caso de fuga.
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 | Deteçã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 a 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, o seu escopo alvo passa a ser web:read e o seu custo é de 2 créditos. Para não quebrar nenhuma chave já emitida, mail:read continua a ser aceite durante um período de transição, mas será retirado: crie as suas novas chaves com web:read e acrescente 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. 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 microserviço ou script tem a sua própria chave com apenas os escopos necessários.
Uma chave por ambiente: dev, staging e produção têm cada um as suas 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 numa chave existente:
- Crie uma nova chave com os escopos desejados.
- Implante-a no seu gestor de segredos.
- Revogue a chave antiga.
Ferramentas CaptainDNS relacionadas
Próximo passo: o modelo de créditos e depois o rate limiting.