Autenticar suas chamadas a API pública

A API pública CaptainDNS autentica requisicoes com uma chave enviada no header HTTP Authorization. Sem OAuth, sem sessão, sem cookies. Este guia cobre o formato das chaves, seu ciclo de vida é as boas praticas de armazenamento.

Envio da chave

POST /public/v1/resolve HTTP/1.1
Host: api.captaindns.com
Authorization: Bearer cdns_live_a3f2XK7mN9QrVtZ4yP1sH6eL8cF2dB5aR3gW7kJxM
Content-Type: application/json

{"qname":"captaindns.com","qtype":"A"}

O schema é sempre Bearer. Qualquer outro schema produz 401 INVALID_API_KEY. As chaves diferenciam maiusculas é minusculas.

Formato das chaves

Uma chave tem tres segmentos:

cdns_<ambiente>_<36 caracteres alfanumericos minusculos>

O prefixo exibido no dashboard é cdns_<env>_ seguido de 8 caracteres. O segredo completo nunca é armazenado no banco; CaptainDNS conserva apenas seu HMAC-SHA256 com pepper.

Ambientes

As chaves cdns_test_* sao tecnicamente identicas as cdns_live_*: mesmos endpoints, mesmos escopos, mesmo consumo de créditos. Existem para que você distinga em logs é dashboards o tráfego de desenvolvimento do de produção. Recomendamos uma chave por ambiente (dev, staging, CI).

Escopos

Cada chave carrega um ou mais escopos. O guia de escopos lista todos; em resumo:

• dns:read: resolução DNS, propagação, DNSSEC, WHOIS de IP.
• mail:read: SPF, DKIM, DMARC, BIMI, MTA-STS, TLS-RPT, DANE, blacklist, SMTP, auditoria de header de email.
• mail:write: deliverability score (unico endpoint atualmente sob este escopo).
• web:read: verificação de URL, crawl de página, detecção de phishing.

Uma chamada a um endpoint cujo escopo não esta presente retorna 403 INSUFFICIENT_SCOPE.

Rotação sem downtime

Uma chave comprometida não se substitui no quente. O fluxo suportado é a rotação:

1. No dashboard ou via the CaptainDNS dashboard, você aciona a rotação.
2. CaptainDNS gera uma nova chave com os mesmos escopos, limites é ambiente.
3. A chave antiga continua válida 7 dias. Nesse período, seus servicos podem migrar progressivamente.
4. Ao final da grace period, a chave antiga é revogada automaticamente.

Atualize seu gerenciador de segredos antes do fim da grace period. Apos esse prazo, qualquer requisicao com a chave antiga retorna 401 REVOKED_API_KEY.

Revogação imediata

Se uma chave vazar (repositorio Git, log, saida de colega), duas opcoes:

• No dashboard: botão Revogar na chave, clique de confirmação. Efeito imediato, sem grace period.
• Via the CaptainDNS dashboard: mesmo efeito, útil para automatizar do CI.

Requisicoes em andamento no momento da revogação terminam; as seguintes retornam 401 REVOKED_API_KEY.

Allowlist de IP

Os planos Business é Enterprise podem restringir uma chave a uma lista de CIDR. A verificação é aplicada antes do handler, entao zero créditos sao consumidos se o IP não estiver autorizado. A resposta é 403 IP_NOT_ALLOWED, com o IP detectado em details.

Exemplo de chave restrita aos runners GitHub Actions é ao backend de produção:

{
  "ip_allowlist": [
    "4.175.114.0/23",
    "52.237.144.10/32"
  ]
}

Atualizar a lista não exige rotação: edite a chave no dashboard é a nova lista entra em efeito em um minuto.

Boas praticas de armazenamento

• Gerenciador de segredos: 1Password, Doppler, AWS Secrets Manager, Vault. Nunca em um arquivo .env commitado nem em YAML CI inline.
• Variavel de ambiente em runtime: injete a chave como variavel de ambiente no inicio do processo.
• Rotação periodica: 90 dias para cargas criticas, 180 dias caso contrario.
• Sem compartilhamento entre times: uma chave por serviço, nada de chave mestra compartilhada por todo o SRE.
• Escopos minimos: se sua integração só faz DMARC check, não conceda web:read nem mail:write.

Detecção de vazamentos

CaptainDNS participa do programa de detecção de secrets do GitHub. Se você publicar por engano uma chave live em um repositorio público, o padrao cdns_live_* é detectado é o owner é notificado. A chave é revogada automaticamente. Você recebera um email com o SHA do commit envolvido é os proximos passos.

Resolução de problemas de autenticação

• 401 INVALID_API_KEY: prefixo ausente ou errado, chave ausente após Bearer, segredo alterado.
• 401 REVOKED_API_KEY: a chave foi revogada manualmente ou automaticamente. Gere uma nova.
• 401 EXPIRED_API_KEY: você definiu expires_at na criacao, a data já passou. Crie uma nova chave ou rotacione antes.
• 403 IP_NOT_ALLOWED: seu IP de origem não esta na allowlist. Verifique também que X-Forwarded-For é propagado corretamente.
• 500 INTERNAL_ERROR: indica problema no lado CaptainDNS; abra um ticket de suporte com o request_id.

Em seguida, passe ao guia de escopos para escolher as permissoes adequadas, ou ao rate limiting se você prepara um cliente de alta frequência.