Autenticar tus llamadas a la API pública

La API pública de CaptainDNS se autentica con una clave enviada en la cabecera HTTP Authorization. Sin OAuth, sin sesión, sin cookies. Esta guia cubre el formato de las claves, su ciclo de vida y las buenas practicas de almacenamiento.

Envio de la clave

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"}

El esquema es siempre Bearer. Cualquier otro esquema produce 401 INVALID_API_KEY. Las claves son sensibles a mayusculas.

Formato de las claves

Una clave tiene tres segmentos:

cdns_<entorno>_<36 caracteres alfanumericos en minuscula>

El prefijo mostrado en el dashboard es cdns_<env>_ seguido de 8 caracteres. El secreto completo no se guarda en la base; CaptainDNS conserva unicamente el HMAC-SHA256 con pimienta.

Entornos

Las claves cdns_test_* son tecnicamente identicas a las cdns_live_*: mismos endpoints, mismos scopes, mismo consumo de créditos. Existen para que distingas en logs y dashboards el trafico de desarrollo del de producción. Recomendamos crear una clave por entorno (dev, staging, CI).

Scopes

Cada clave lleva uno o mas scopes. La guia de scopes los detalla; en resumen:

• dns:read: resolución DNS, propagación, DNSSEC, WHOIS de IP.
• mail:read: SPF, DKIM, DMARC, BIMI, MTA-STS, TLS-RPT, DANE, blacklist, SMTP, auditoria de cabeceras.
• mail:write: score de deliverability (unico endpoint actualmente en este scope).
• web:read: verificación de URL, crawl de página, detección de phishing.

Una llamada a un endpoint cuyo scope no esta presente devuelve 403 INSUFFICIENT_SCOPE.

Rotación sin interrupción

Una clave comprometida no se reemplaza a lo bruto. El flujo soportado es la rotación:

1. Desde el dashboard o mediante the CaptainDNS dashboard, lanzas la rotación.
2. CaptainDNS genera una nueva clave con los mismos scopes, límites y entorno.
3. La clave antigua sigue activa 7 dias. Durante este período, tus servicios pueden migrar progresivamente.
4. Al vencer el grace period, la clave antigua se revoca automaticamente.

Actualiza tu gestor de secretos antes del final del grace period. Pasado ese plazo, toda peticion con la clave antigua devuelve 401 REVOKED_API_KEY.

Revocación inmediata

Si una clave se filtra (repositorio Git, log, baja de un companero), dos opciones:

• Desde el dashboard: boton Revocar en la clave, clic de confirmacion. Efecto inmediato, sin grace period.
• Via the CaptainDNS dashboard: mismo efecto, útil para automatizar desde CI.

Las peticiones en curso al momento de la revocación se completan; las siguientes devuelven 401 REVOKED_API_KEY.

Allowlist de IP

Los planes Business y Enterprise permiten restringir una clave a una lista de CIDR. La verificación se aplica antes del handler, por lo que una peticion no consume créditos si la IP no esta autorizada. La respuesta es 403 IP_NOT_ALLOWED, con la IP detectada en details.

Ejemplo de clave restringida a los runners de GitHub Actions y al backend de producción:

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

Actualizar la lista no exige rotación: edita la clave desde el dashboard y la nueva lista surte efecto en un minuto.

Buenas practicas de almacenamiento

• Gestor de secretos: 1Password, Doppler, AWS Secrets Manager, Vault. Nunca en un archivo .env en git ni en un YAML de CI.
• Variable de entorno en runtime: inyecta la clave como variable de entorno al arrancar el proceso.
• Rotación periodica: 90 dias para cargas criticas, 180 dias en caso contrario. Planifica con un recordatorio o un job de CI.
• Sin compartir entre equipos: una clave por servicio, nunca una clave maestra compartida por todo el equipo SRE.
• Scopes minimos: si tu integración solo hace DMARC check, no concedas web:read ni mail:write. Limita el blast radius.

Detección de fugas

CaptainDNS esta inscrito en el programa de detección de secretos de GitHub. Si subes por error una clave live a un repositorio publico, el patron cdns_live_* se detecta y el propietario recibe una notificación. La clave se revoca automaticamente. Recibiras un email con el SHA del commit implicado y los siguientes pasos.

Resolución de problemas de autenticación

• 401 INVALID_API_KEY: prefijo ausente o incorrecto, clave tras Bearer, secreto alterado. Verifica que no haya espacios ni saltos de linea en tu cliente.
• 401 REVOKED_API_KEY: la clave fue revocada manual o automaticamente. Genera una nueva.
• 401 EXPIRED_API_KEY: definiste expires_at en la creacion y la fecha ya paso. Crea una nueva clave o rota esta antes.
• 403 IP_NOT_ALLOWED: tu IP origen no esta en la allowlist. Verifica también que tu proxy reverso propague correctamente X-Forwarded-For.
• 500 INTERNAL_ERROR: problema del lado CaptainDNS, abre un ticket de soporte con el request_id.

A continuacion, pasa a la guia de scopes para elegir los permisos adecuados, o al rate limiting si preparas un cliente de alta frecuencia.