Authentification & Clés API

Méthodes d'authentification

YesWeCheck supporte deux méthodes pour les intégrations backend :

Méthode	Header	Expiration	Usage recommandé
API Key	Authorization: Bearer ywc_live_<key>	Jamais	Backend, intégrations longue durée
JWT	Authorization: Bearer <token>	15 min	Accès programmatique avec refresh

Les deux méthodes passent par le même header Authorization, en schéma Bearer. L'API distingue les deux d'après la valeur : un token préfixé ywc_live_ / ywc_test_ est traité comme une clé API, tout le reste comme un JWT.

Recommandé pour la production

L'authentification par API Key est la méthode standard pour toutes les intégrations. Elle n'expire pas et se configure en quelques secondes depuis le Dashboard.

Header X-API-Key

Ce header n'est pas supporté et renvoie 401 No authorization header. Une version antérieure de cette documentation le mentionnait par erreur. Utilisez Authorization: Bearer <clé>.

---

Authentification par API Key

Obtenir une clé API

1. Connectez-vous sur app.yeswecheck.fr
2. Settings → API Keys → Créer une nouvelle clé
3. Copiez la clé immédiatement — elle ne sera plus affichée

Utiliser la clé API

cURL

curl -X POST https://api.yeswecheck.fr/v2/email/validate \
  -H "Authorization: Bearer ywc_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

JavaScript (Node.js)

// Recommandé : stocker dans les variables d'environnement
const API_KEY = process.env.YESWECHECK_API_KEY;

const response = await fetch('https://api.yeswecheck.fr/v2/email/validate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: '[email protected]' }),
});

Python

import os
import requests

API_KEY = os.environ["YESWECHECK_API_KEY"]

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})

response = session.post(
    "https://api.yeswecheck.fr/v2/email/validate",
    json={"email": "[email protected]"},
)

Configurer une clé API

Lors de la création depuis le Dashboard, vous pouvez configurer :

{
  "name": "Production",
  "allowedDomains": ["monsite.fr", "www.monsite.fr"],
  "config": {
    "smtp": false,
    "disposable": true,
    "roleAccount": true,
    "enrichment": false,
    "randomDetection": true
  }
}

Option	Par défaut	Description
smtp	false	Autoriser la vérification SMTP via cette clé
disposable	true	Activer la détection d'emails jetables
roleAccount	true	Activer la détection de role accounts
enrichment	false	Activer l'enrichissement (prénom probable)
randomDetection	true	Activer la détection d'emails aléatoires

---

Renouveler un token JWT (Refresh)

Si votre intégration utilise l'authentification JWT, l'accessToken expire après 15 minutes. Utilisez le refreshToken pour en obtenir un nouveau sans re-authentification :

curl -X POST https://api.yeswecheck.fr/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "VOTRE_REFRESH_TOKEN"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "expiresIn": 900
}

info

Les tokens JWT sont gérés par la plateforme app.yeswecheck.fr. Pour une intégration purement API, les API Keys sont suffisantes et ne nécessitent pas de refresh.

---

Environnements

Environnement	Base URL	Usage
Production	https://api.yeswecheck.fr/v2	Applications en production
Local	http://localhost:3000/v2	Développement

Variables d'environnement

# Production
YESWECHECK_API_URL=https://api.yeswecheck.fr/v2
YESWECHECK_API_KEY=ywc_live_...

# Local / Dev
YESWECHECK_API_URL=http://localhost:3000/v2
YESWECHECK_API_KEY=ywc_test_...

---

Sécurité des clés API

Ne jamais exposer une clé API côté client

• ❌ const API_KEY = "ywc_live_abc123" dans du JavaScript navigateur
• ❌ Clé API committée dans le dépôt Git
• ✅ Variable d'environnement serveur : process.env.YESWECHECK_API_KEY
• ✅ Pour les formulaires côté client → créer une clé avec allowedDomains restreints

Restriction par domaine

Pour les appels depuis un navigateur (formulaires HTML), créez une clé avec allowedDomains :

{
  "name": "Frontend Formulaire",
  "allowedDomains": ["monsite.fr"],
  "config": { "smtp": false }
}

La clé ne fonctionnera que si la requête provient de monsite.fr — même si elle est visible dans le HTML.

Rotation en cas de compromission

1. POST /v2/api-keys/{id}/revoke — Désactive immédiatement la clé
2. Depuis le Dashboard → créez une nouvelle clé
3. Mettez à jour vos variables d'environnement
4. DELETE /v2/api-keys/{id} — Supprimez l'ancienne clé

Consultez le Guide Gestion des Clés API pour plus de détails.