Choisir les scopes adaptés à son intégration
Les scopes restreignent ce qu'une clé API peut faire. Une clé porte un ou plusieurs scopes ; un appel vers un endpoint dont le scope n'est pas présent retourne 403 INSUFFICIENT_SCOPE. Adoptez le principe du moindre privilège : donnez à chaque clé le minimum de scopes requis par l'intégration qu'elle sert.
Scopes disponibles
L'API publique V1 expose quatre scopes :
| Scope | Intention | Exemple d'usage |
|---|---|---|
dns:read | Lecture de données DNS | Watcher DNS, scripts de CI, outil de troubleshooting |
mail:read | Diagnostics d'authentification email | Audit SPF/DKIM/DMARC, monitoring délivrabilité |
mail:write | Opérations coûteuses liées au score d'email | Score de délivrabilité, génération DMARC |
web:read | Analyse de pages et d'URL | Détection phishing, vérification de liens dans un produit |
Aucun scope n'implique un autre. mail:write n'hérite pas de mail:read : si votre clé fait du DMARC check et du score de délivrabilité, elle doit porter les deux scopes.
Mapping complet des endpoints
dns:read
| Endpoint | Crédits | Description |
|---|---|---|
POST /public/v1/resolve | 1 | Résolution DNS standard |
POST /public/v1/resolve/propagation | 3 | Test de propagation multi-resolvers |
POST /public/v1/dnssec/check | 3 | Vérification de la chaîne DNSSEC |
POST /public/v1/ip/whois | 2 | WHOIS d'une adresse IP |
POST /public/v1/ip/nslookup | 1 | Reverse DNS (PTR) |
POST /public/v1/ip/netmask | 1 | Calculateur de masque IPv4 |
POST /public/v1/rdap/lookup | 2 | RDAP/WHOIS de domaine |
POST /public/v1/domain/dns-check | 5 | Audit de serveurs DNS |
mail:read
| Endpoint | Crédits | Description |
|---|---|---|
POST /public/v1/spf/lookup | 1 | Lookup et parsing SPF |
POST /public/v1/spf/validate | 1 | Validation SPF (sans lookup DNS) |
POST /public/v1/dkim/lookup | 1 | Lookup DKIM par sélecteur |
POST /public/v1/dkim/validate | 1 | Validation DKIM (sans lookup DNS) |
POST /public/v1/dmarc/lookup | 1 | Lookup et parsing DMARC |
POST /public/v1/dmarc/validate | 1 | Validation DMARC (sans lookup DNS) |
POST /public/v1/bimi/lookup | 2 | Lookup BIMI avec récupération du logo |
POST /public/v1/bimi/validate | 2 | Validation BIMI (sans lookup DNS) |
POST /public/v1/bimi/logo/lookup | 2 | Téléchargement et validation de logo BIMI |
POST /public/v1/mta-sts/lookup | 2 | Lookup de la policy MTA-STS |
POST /public/v1/tls-rpt/lookup | 2 | Lookup TLS-RPT |
POST /public/v1/dane/lookup | 2 | Lookup DANE/TLSA pour SMTP |
POST /public/v1/blacklist/ip | 5 | Check blacklist multi-RBL |
POST /public/v1/smtp/check | 6 | Test SMTP (HELO, STARTTLS, AUTH) |
POST /public/v1/mail/header-audit | 2 | Analyse d'un header brut d'email |
POST /public/v1/mail/header-analyze | 2 | Analyse de headers email |
POST /public/v1/mail/domain-check | 10 | Audit complet de domaine email |
POST /public/v1/dmarcbis/check | 2 | Analyse DMARCbis Tree Walk |
POST /public/v1/dmarc/report/analyze | 5 | Analyse de rapport DMARC agrégé |
POST /public/v1/certificates/csr/parse | 1 | Parsing de CSR |
POST /public/v1/certificats/bimi/parse | 1 | Parsing de certificat BIMI/VMC |
POST /public/v1/certificats/bimi/lookup | 2 | Téléchargement et parsing de certificat BIMI |
mail:write
| Endpoint | Crédits | Description |
|---|---|---|
POST /public/v1/deliverability/score | 30 | Score agrégé DMARC, BIMI, réputation |
POST /public/v1/dmarc/generate | 1 | Générateur d'enregistrement DMARC |
POST /public/v1/dmarcbis/migrate | 1 | Migration DMARC vers DMARCbis |
Le scope mail:write isole les endpoints de modification. Il est recommandé de créer une clé dédiée si votre intégration utilise le score de délivrabilité, afin de réduire l'impact en cas de fuite.
web:read
| Endpoint | Crédits | Description |
|---|---|---|
POST /public/v1/url/check | 3 | Analyse de chaîne de redirections |
POST /public/v1/page/crawl-check | 10 | Crawl d'une page et extraction de meta |
POST /public/v1/phishing/check | 8 | Détection phishing heuristique |
Stratégies d'attribution
Clé unique tous scopes (fragile, déconseillé) : vous donnez à un seul secret l'accès à toute l'API. Pratique pour prototyper, dangereux en production. Passez à une stratégie multi-clés dès que l'intégration est stable.
Une clé par service (recommandé) : chaque microservice ou script porte sa propre clé, avec uniquement les scopes dont il a besoin. Si un service fuite sa clé, l'incident reste circonscrit à son périmètre.
Une clé par environnement : dev, staging, prod ont chacun leur jeu de clés, distinguées par préfixe (cdns_test_* vs cdns_live_*) et par nom dans le dashboard. Simplifie les dashboards de consommation et les alertes.
Clé à scope unique pour mail:write : séparer le score de délivrabilité (30 crédits) du reste évite qu'une boucle involontaire sur ce seul endpoint ne ruine votre quota. La clé dédiée peut aussi avoir un rate limit applicatif plus strict côté client.
Ajouter ou retirer un scope
Les scopes sont fixés à la création de la clé. Pour modifier les scopes d'une clé existante :
- Créez une nouvelle clé avec les scopes désirés.
- Déployez la nouvelle clé dans votre secret manager.
- Révoquez l'ancienne clé.
Cette procédure évite qu'un scope retiré ne casse subitement une intégration en cours d'exécution. Les grandes rotations de scopes peuvent aussi passer par la rotation avec grace period si la structure générale reste la même.
Outils CaptainDNS liés
Les outils web suivants couvrent les mêmes diagnostics. Utiles pour valider à la main un résultat surprenant de l'API :
Prochaine étape : comprenez le modèle de credits pour estimer le coût mensuel de votre intégration, puis lisez le rate limiting.