Authentification et clés API
Toutes les requêtes authentifiées passent par un seul en-tête, Authorization, avec le schéma Bearer :
Authorization: Bearer ywc_live_xxxxxxxxxxxxxxxxxxxxxxxx
| Forme | Statut |
|---|---|
Authorization: Bearer ywc_live_… ou ywc_test_… | Forme recommandée |
Authorization: ywc_live_… (sans Bearer) | Acceptée pour compatibilité avec les intégrations anciennes |
X-API-Key: ywc_live_… | Jamais lue : la requête reçoit 401 No authorization header |
L'API reconnaît une clé à son préfixe. Toute autre valeur précédée de Bearer est traitée comme un jeton de session du tableau de bord (JWT, valable 60 minutes), réservé à l'application app.yeswecheck.fr. Pour une intégration, utilisez toujours une clé API : elle n'expire pas.
Créer une clé
Depuis Clés API dans le tableau de bord. Seuls les rôles owner et admin d'une organisation peuvent créer, modifier, faire tourner ou révoquer une clé. Le secret complet n'est affiché qu'une fois, à la création ; le tableau de bord ne montre ensuite que son préfixe et ses 4 derniers caractères.
ywc_live_ ou ywc_test_
Le choix est fait à la création et ne peut plus changer. Les deux préfixes se comportent de la même façon : mêmes contrôles, mêmes crédits, même facturation. Le préfixe test sert seulement à distinguer vos clés de recette dans vos journaux et dans les statistiques.
Ce que règle une clé
Les contrôles actifs
Chaque clé porte sa liste de contrôles. Ils sont tous actifs par défaut, sauf le SMTP, désactivé par défaut.
| Contrôle | Champ de la clé | Défaut |
|---|---|---|
| Vérification SMTP de la boîte | smtp | désactivé |
| Adresse jetable | disposable | activé |
| Domaine malveillant | maliciousDomains | activé |
| Faute de frappe dans le domaine | typoDomain | activé |
| Domaine piège (typosquat) | typosquat | activé |
| Compte générique (contact@, info@…) | roleAccount | activé |
| Adresse noreply (noreply@, mailer-daemon@…) | noReply | activé |
| Partie locale aléatoire | randomDetection | activé |
| Terme injurieux | profanity | activé |
Sous-adressage (+tag) | aliasing | activé |
| Prénom, nom, genre, âge présumé | enrichment | activé |
| Listes blanche et noire de l'organisation | whitelist · blacklist | activé |
| Santé du domaine | domainHealth | activé |
| Réseau de l'appelant (Tor, VPN, datacenter) | network | activé |
Avec une clé API, seule la configuration de la clé décide si le SMTP est exécuté. Un champ smtp envoyé dans le corps est accepté mais ignoré, sans erreur ni avertissement ; il en va de même pour enrichment. Pour faire coexister des appels avec et sans SMTP, créez deux clés.
Un contrôle désactivé n'apparaît plus dans features de la réponse. La syntaxe et le DNS sont toujours exécutés et toujours renvoyés.
La portée : server ou widget
| Portée | Usage |
|---|---|
server | Clé secrète, appelée depuis votre serveur. C'est la portée de toute clé créée depuis Clés API. |
widget | Clé rattachée à un widget de formulaire. Elle n'apparaît jamais dans la page : le snippet ne contient que l'identifiant du widget. Une clé widget exige au moins un domaine autorisé. |
La portée n'est pas modifiable : elle est posée quand vous rattachez une clé à un widget depuis Widgets.
Les restrictions d'IP et d'origine
Deux listes facultatives, de 20 entrées au plus chacune, limitent qui peut utiliser la clé :
| Restriction | Contrôle | Format |
|---|---|---|
allowedIps | Adresse IP de l'appelant | IPv4 ou IPv6, adresse seule ou plage CIDR (au plus /16 en IPv4, /32 en IPv6) |
allowedDomains | En-tête Origin de la requête | exemple.fr ou *.exemple.fr (le joker couvre aussi exemple.fr) |
- Sans restriction, la clé est utilisable depuis n'importe où.
- Avec les deux listes, l'appel doit satisfaire les deux : IP autorisée et origine autorisée.
- Un appel refusé reçoit
403, avec un message qui précise la restriction en cause, et la tentative est journalisée dans le tableau de bord.
Un appel serveur à serveur (cURL, backend, outil d'automatisation) n'envoie pas d'en-tête Origin. Une clé avec allowedDomains les refuse donc tous. Pour une clé serveur, restreignez par IP. La restriction d'origine sert aux clés de widget.
Les plafonds de crédits
Une clé peut recevoir un plafond journalier (maxCreditsPerDay) et un plafond mensuel (maxCreditsPerMonth). Ils bornent ce que coûterait une clé dont le secret aurait fuité, indépendamment du solde de l'organisation.
- Seuls les crédits réellement débités comptent (un verdict
unknownne compte pas). - Le plafond journalier se réinitialise à 00:00 UTC, le mensuel le 1er du mois à 00:00 UTC.
- Une alerte est envoyée au propriétaire à 50 %, 80 % puis 100 % du plafond.
- À ne pas confondre avec la limite d'appels de la clé (60/min, 1 000/h, 10 000/j par défaut), qui compte les appels et non les crédits :
429 API_KEY_RATE_LIMITED, voir Limites de débit. - Plafond atteint :
429avec le codeAPI_KEY_BUDGET_EXCEEDEDet un en-têteRetry-After. Ce n'est pas un manque de crédits : inutile de recharger, attendez la réinitialisation ou relevez le plafond. Voir Codes d'erreur.
La politique de validation
Une clé peut être rattachée à une politique (Règles de validation dans le tableau de bord) qui transforme les signaux en décision métier : refuser les jetables, les comptes génériques, les domaines accept-all… Sans politique explicite, celle par défaut de l'organisation s'applique. Voir Politiques et listes.
Les clés des assistants IA
Le serveur MCP (https://api.yeswecheck.fr/mcp) accepte une clé de portée server, avec le même en-tête Authorization: Bearer. Les assistants comme Claude ou ChatGPT se connectent plutôt par OAuth : à l'autorisation, YesWeCheck crée une clé dédiée à l'application, marquée MCP · OAuth dans Clés API. Son secret n'est jamais affiché et elle ne se fait pas tourner ; la révoquer coupe l'application. La recherche d'email BtoB n'est accessible qu'au serveur MCP, si la clé a l'option Finder BtoB pour les agents IA.
Remplacer une clé sans coupure
La rotation génère un nouveau secret pour la même clé : configuration, restrictions, plafonds et statistiques sont conservés. Vous choisissez pendant combien de temps l'ancien secret reste accepté :
| Période de grâce | Effet |
|---|---|
| Aucune (défaut) | L'ancien secret est refusé immédiatement |
| 24 heures · 7 jours · 30 jours | Les deux secrets fonctionnent pendant la période, le temps de redéployer |
- Dans Clés API, lancez la rotation avec une période de grâce adaptée à votre cycle de déploiement.
- Copiez le nouveau secret et déployez-le dans vos variables d'environnement.
- Vérifiez dans les statistiques de la clé que le trafic passe bien par le nouveau secret.
En cas de fuite avérée, révoquez la clé : elle est refusée immédiatement (401 Invalid or revoked API key). Une clé révoquée peut être réactivée tant qu'elle n'a pas été supprimée.
Bonnes pratiques
- Une clé par usage et par environnement : production, recette, outil d'automatisation, chacun son widget.
- Le secret vit côté serveur, dans une variable d'environnement ou un coffre-fort de secrets. Jamais dans un dépôt Git, une application mobile ou du JavaScript servi au navigateur.
- Pour un formulaire web, n'exposez aucune clé : utilisez le widget, conçu pour ça.
- Posez un plafond de crédits sur toute clé qui a le SMTP activé.
- Restreignez les clés serveur à l'IP de sortie de vos serveurs quand elle est fixe.