Authentifier ses appels à l'API publique

L'API publique CaptainDNS s'authentifie avec une clé API envoyée dans le header HTTP Authorization. Pas d'OAuth, pas de session, pas de cookies. Ce guide couvre le format des clés, leur cycle de vie et les bonnes pratiques de stockage.

Envoi de la clé

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

Le schéma est toujours Bearer. Un autre schéma déclenche 401 INVALID_API_KEY. Les clés sont sensibles à la casse.

Format des clés

Une clé contient trois segments :

cdns_<environnement>_<36 caracteres alphanumeriques minuscules>

Le préfixe affichable côté dashboard est cdns_<env>_ suivi de 8 caractères. Le secret complet n'est jamais stocké en base ; CaptainDNS conserve seulement son HMAC-SHA256 poivre.

Environnements

Les clés cdns_test_* sont techniquement identiques aux clés cdns_live_* : mêmes endpoints, mêmes scopes, même consommation de credits. Elles existent pour vous permettre de distinguer, dans vos logs et vos dashboards, le trafic de développement du trafic de production. Nous vous recommandons d'en créer une par environnement (dev, staging, CI).

Scopes

Chaque clé porte un ou plusieurs scopes. Le guide des scopes détaille la liste complète ; en résumé :

• dns:read : résolution DNS, propagation, DNSSEC, WHOIS IP.
• mail:read : SPF, DKIM, DMARC, BIMI, MTA-STS, TLS-RPT, DANE, blacklist, SMTP, audit de header d'email.
• mail:write : score de délivrabilité (seul endpoint actuellement rattaché à ce scope).
• web:read : vérification d'url, crawl de page, détection de phishing.

Un appel à un endpoint dont le scope n'est pas présent sur la clé retourne 403 INSUFFICIENT_SCOPE.

Rotation sans interruption

Une clé compromise ou obsolète ne se recrée pas à l'arrache. Le flux supporté est la rotation :

1. Depuis le dashboard CaptainDNS, vous déclenchez la rotation sur la clé concernée.
2. CaptainDNS génère une nouvelle clé avec les mêmes scopes, mêmes limites, même environnement.
3. L'ancienne clé reste valide 7 jours. Pendant cette période, vos services peuvent migrer progressivement.
4. À l'expiration de la grace period, l'ancienne clé est automatiquement révoquée.

Pensez à mettre à jour votre gestionnaire de secrets avant la fin de la grace period. Passé ce délai, toute requête avec l'ancienne clé renvoie 401 REVOKED_API_KEY.

Révocation immédiate

Si une clé fuite en public (repository Git, log, alerte remontée par captaindns.com via la détection de secrets GitHub, collègue qui part), deux options :

• Depuis le dashboard : bouton Révoquer sur la clé, clic de confirmation. Effet immédiat, aucune grace period.

Les requêtes en cours au moment de la révocation aboutissent ; les suivantes renvoient 401 REVOKED_API_KEY.

IP allowlist

Les plans Business et Enterprise peuvent restreindre une clé à une liste de CIDR. La restriction est appliquée en amont du handler, donc la requête consomme zéro credit si l'IP n'est pas autorisée. Le code de retour est 403 IP_NOT_ALLOWED, avec l'IP détectée dans details.

Exemple de clé restreinte aux IP de votre worker GitHub Actions et de votre backend prod :

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

Mettre à jour la liste n'exige pas de rotation : modifiez la clé depuis le dashboard, la nouvelle liste prend effet dans la minute qui suit.

Bonnes pratiques de stockage

• Gestionnaire de secrets : 1Password, Doppler, AWS Secrets Manager, Vault. Jamais dans un fichier .env commit ni dans un YAML de CI inline.
• Variable d'environnement au runtime : injectez la clé via variable d'environnement au démarrage du process. Évitez les fichiers montés en clair.
• Rotation périodique : 90 jours pour les usages critiques, 180 jours sinon. Planifiez-la avec un rappel calendrier ou mieux, un job CI.
• Zero partage inter-équipes : une clé par service, pas une clé maître partagée par tout le SRE. La révocation d'incident devient chirurgicale.
• Scopes minimaux : si votre intégration fait seulement du DMARC check, ne donnez pas web:read ni mail:write. Limitez le blast radius.

Détection automatique des fuites

CaptainDNS est inscrit au programme de détection de secrets de GitHub. Si vous poussez par erreur une clé live dans un dépôt public, le pattern cdns_live_* est détecté et une notification est envoyée à l'owner. La clé est automatiquement révoquée. Vous recevez un email avec le SHA du commit incriminé et la marche à suivre pour émettre une nouvelle clé.

Résolution des soucis d'auth

• 401 INVALID_API_KEY : préfixe absent ou mauvais, clé manquante après Bearer, secret altéré. Vérifiez qu'aucun espace ou saut de ligne ne s'est glissé dans votre client.
• 401 REVOKED_API_KEY : la clé a été révoquée manuellement ou automatiquement. Générez-en une nouvelle.
• 401 EXPIRED_API_KEY : vous avez défini expires_at à la création, la date est passée. Créez une nouvelle clé ou rotez celle-ci avant.
• 403 IP_NOT_ALLOWED : votre IP source n'est pas dans l'allowlist. Vérifiez aussi que le header X-Forwarded-For traverse bien votre proxy (les IP privées RFC1918 sont ignorées et le hop immédiat est utilisé).
• 500 INTERNAL_ERROR : indique un problème côté CaptainDNS, ouvrez un ticket support avec le request_id.

Passez ensuite au guide des scopes pour choisir les permissions adaptées, ou consultez le rate limiting si vous préparez un client haute fréquence.