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 guía cubre el formato de las claves, su ciclo de vida y las buenas prácticas de almacenamiento.

Envío 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 mayúsculas.

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 únicamente el HMAC-SHA256 con pepper.

Entornos

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

Scopes

Cada clave lleva uno o más scopes. La guía 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, auditoría de cabeceras.
• mail:write: score de entregabilidad, generador de registro DMARC, migración de DMARC a DMARCbis, re-resolución forzada de un perfil SPF alojado.
• web:read: verificación de URL, crawl de página, detección de phishing.

Una llamada a un endpoint cuyo scope no está presente en la clave devuelve 403 INSUFFICIENT_SCOPE.

Rotación sin interrupción

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

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

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

Revocación inmediata

Si una clave se filtra (repositorio Git, log, baja de un compañero), la revocación se hace desde el dashboard: botón Revocar en la clave y clic de confirmación. Efecto inmediato, sin grace period.

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 petición no consume créditos si la IP no está autorizada. La respuesta es 403 IP_NOT_ALLOWED.

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 prácticas 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 periódica: 90 días para cargas críticas, 180 días 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 mínimos: si tu integración solo hace DMARC check, no concedas web:read ni mail:write. Limita el blast radius.

Resolución de problemas de autenticación

• 401 INVALID_API_KEY: prefijo ausente o incorrecto, clave ausente tras Bearer, secreto alterado. Verifica que no haya espacios ni saltos de línea en tu cliente.
• 401 REVOKED_API_KEY: la clave fue revocada manual o automáticamente. Genera una nueva.
• 401 EXPIRED_API_KEY: definiste expires_at en la creación y la fecha ya pasó. Crea una nueva clave o rota esta antes.
• 403 IP_NOT_ALLOWED: tu IP origen no está en la allowlist. La IP cliente se deriva únicamente de r.RemoteAddr. Si tu tráfico pasa por un proxy, CaptainDNS reescribe RemoteAddr a partir de X-Forwarded-For solo cuando el peer inmediato pertenece a la lista de CIDR de proxies de confianza configurada en la plataforma. Un X-Forwarded-For colocado por un cliente arbitrario no se honra nunca.
• 500 INTERNAL_ERROR: problema del lado CaptainDNS, abre un ticket de soporte con el request_id.

A continuación, pasa a la guía de scopes para elegir los permisos adecuados, o al rate limiting si preparas un cliente de alta frecuencia.