Aller au contenu principal

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
FormeStatut
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ôleChamp de la cléDéfaut
Vérification SMTP de la boîtesmtpdésactivé
Adresse jetabledisposableactivé
Domaine malveillantmaliciousDomainsactivé
Faute de frappe dans le domainetypoDomainactivé
Domaine piège (typosquat)typosquatactivé
Compte générique (contact@, info@…)roleAccountactivé
Adresse noreply (noreply@, mailer-daemon@…)noReplyactivé
Partie locale aléatoirerandomDetectionactivé
Terme injurieuxprofanityactivé
Sous-adressage (+tag)aliasingactivé
Prénom, nom, genre, âge présuméenrichmentactivé
Listes blanche et noire de l'organisationwhitelist · blacklistactivé
Santé du domainedomainHealthactivé
Réseau de l'appelant (Tor, VPN, datacenter)networkactivé
Le SMTP ne se demande pas dans la requête

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éeUsage
serverClé secrète, appelée depuis votre serveur. C'est la portée de toute clé créée depuis Clés API.
widgetClé 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é :

RestrictionContrôleFormat
allowedIpsAdresse IP de l'appelantIPv4 ou IPv6, adresse seule ou plage CIDR (au plus /16 en IPv4, /32 en IPv6)
allowedDomainsEn-tête Origin de la requêteexemple.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.
Une restriction d'origine bloque les appels serveur

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 unknown ne 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 : 429 avec le code API_KEY_BUDGET_EXCEEDED et un en-tête Retry-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âceEffet
Aucune (défaut)L'ancien secret est refusé immédiatement
24 heures · 7 jours · 30 joursLes deux secrets fonctionnent pendant la période, le temps de redéployer
  1. Dans Clés API, lancez la rotation avec une période de grâce adaptée à votre cycle de déploiement.
  2. Copiez le nouveau secret et déployez-le dans vos variables d'environnement.
  3. 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.