Autenticar suas chamadas à API pública

A API pública CaptainDNS autentica requisições 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 e as boas práticas 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 maiúsculas e minúsculas.

Formato das chaves

Uma chave tem três 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_* são tecnicamente idênticas às cdns_live_*: mesmos endpoints, mesmos escopos, mesmo consumo de créditos. Existem para que você distinga em logs e 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 (único 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 está presente retorna 403 INSUFFICIENT_SCOPE.

Rotação sem downtime

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

1. No dashboard CaptainDNS, você aciona a rotação na chave em questão.
2. CaptainDNS gera uma nova chave com os mesmos escopos, limites e ambiente.
3. A chave antiga continua válida 7 dias. Nesse período, seus serviços 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. Após esse prazo, qualquer requisição com a chave antiga retorna 401 REVOKED_API_KEY.

Revogação imediata

Se uma chave vazar (repositório Git, log, saída de um colega), duas opções:

• No dashboard: botão Revogar na chave, clique de confirmação. Efeito imediato, sem grace period.

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

Allowlist de IP

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

Exemplo de chave restrita aos runners GitHub Actions e 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 e a nova lista entra em efeito em um minuto.

Boas práticas de armazenamento

• Gerenciador de segredos: 1Password, Doppler, AWS Secrets Manager, Vault. Nunca em um arquivo .env commitado nem em YAML CI inline.
• Variável de ambiente em runtime: injete a chave como variável de ambiente no início do processo.
• Rotação periódica: 90 dias para cargas críticas, 180 dias caso contrário.
• Sem compartilhamento entre times: uma chave por serviço, nada de chave mestra compartilhada por todo o SRE.
• Escopos mínimos: se sua integração só faz DMARC check, não conceda web:read nem mail:write.

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 criação, a data já passou. Crie uma nova chave ou rotacione antes.
• 403 IP_NOT_ALLOWED: seu IP de origem não está na allowlist. O IP do cliente é derivado somente de r.RemoteAddr. Se seu tráfego passa por um proxy, o CaptainDNS reescreve RemoteAddr previamente a partir de X-Forwarded-For apenas quando o peer imediato pertence à lista de CIDRs de proxies de confiança configurada na plataforma. Um X-Forwarded-For enviado por um cliente arbitrário nunca é considerado.
• 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 permissões adequadas, ou ao rate limiting se você prepara um cliente de alta frequência.