Périmètre sûr : ce guide s'applique uniquement à vos propres applications — environnements de QA, de préproduction ou de production — ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni la résolution de défis sur des services que vous n'exploitez pas.
Better-Auth place souvent un CAPTCHA sur la page de connexion ou d'inscription pour filtrer le trafic automatisé. Dès que vous voulez tester ce parcours de bout en bout — en intégration continue, dans un job planifié ou depuis une suite E2E — ce même CAPTCHA bloque vos propres scripts. CaptchaAI résout le token à la volée et vous le réinjectez dans Better-Auth au sein de la même session : votre test franchit l'étape sans intervention humaine, et reste stable quand la protection évolue.
L'enjeu n'est pas de faire tourner le flux une fois, mais de le rendre fiable sans surveillance : latence prévisible et échecs propres.
Où le CAPTCHA intervient dans Better-Auth
Le plugin CAPTCHA de Better-Auth s'insère avant la vérification des identifiants : la requête de connexion transporte un token que le serveur valide auprès du fournisseur (reCAPTCHA v2/v3, Cloudflare Turnstile). CaptchaAI prend en charge ces familles. En revanche, CaptchaAI ne résout pas hCaptcha ni FunCaptcha (Arkose Labs) : si votre configuration Better-Auth s'appuie sur ces types, ce guide ne s'applique pas à eux.
Concrètement, votre harnais de test doit produire un token valide pour le sitekey de votre page, puis l'injecter exactement là où le navigateur réel le placerait.
Architecture cible
Un composant interne de votre suite appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans le formulaire ou la route d'API Better-Auth. Tracez chaque étape : vous repérez ainsi une régression dès la montée de version, pas trois jours plus tard en production.
Le déroulé de résolution, étape par étape
L'ordre compte. Chaque étape ferme une source d'erreur fréquente.
- Ne capturez que les paramètres utiles. Inspectez la page ou l'appel réseau et relevez uniquement ce que la famille CAPTCHA attend : sitekey, URL de page, action, proxy éventuel. Stocker davantage crée de fausses pistes de débogage.
- Envoyez la tâche à l'endpoint de soumission. Tout statut d'échec doit être traité comme une erreur : journalisez la réponse complète et remontez-la vers votre canal de supervision.
- Interrogez le résultat régulièrement. Attendez 15 secondes avant la première interrogation, puis toutes les 5 secondes, avec un plafond ferme de 120 secondes par tâche.
- Appliquez le token dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même client HTTP, même jar de cookies. Une session incohérente est la première cause de rejet après résolution.
- Mesurez la latence, les retries et l'acceptation en aval. Réussir la résolution et réussir le parcours de connexion sont deux métriques distinctes ; suivez les deux.
Exemple de code
Appel HTTP côté serveur, dans votre propre service, pour créer une tâche Turnstile :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Gérer les secrets et l'observabilité
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, jamais dans le code source. Le déploiement la monte en variable d'environnement au runtime.
Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry) : vous rejouez ainsi un scénario complet depuis un seul identifiant. Côté RGPD, limitez les données personnelles dans ces journaux — un identifiant de tâche et un horodatage suffisent.
Mesurer la réussite
Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée.
| Indicateur | Cible | Ce qu'il révèle |
|---|---|---|
| Latence première résolution (p50) | < 25 s pour les CAPTCHA à token, < 8 s pour l'OCR d'image | L'intégration est saine et n'attend pas de retries. |
| Latence première résolution (p95) | < 60 s pour les CAPTCHA à token | La traîne est contenue et vos timeouts sont bien dimensionnés. |
| Taux de réussite de résolution | ≥ 95 % par famille de CAPTCHA | Vos paramètres sont corrects et correspondent au défi réel. |
| Acceptation de bout en bout | ≥ 95 % après injection du token | Better-Auth accepte le token dans la session où vous l'avez appliqué. |
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez avant de réessayer et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Un paramètre requis manque ou est mal formé. | Revalidez l'URL de page, le sitekey et les champs spécifiques face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Gardez la résolution et l'envoi du formulaire dans le même contexte. |
Liste de contrôle
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est dans un coffre ou un secret CI, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, couvre les erreurs transitoires.
- Les tests sont rejouables depuis votre intégration continue.
FAQ
Quel plan CaptchaAI choisir pour une suite de tests Better-Auth ?
La facturation se fait par thread, avec des résolutions illimitées par thread. Pour une suite E2E qui lance quelques connexions en parallèle, le plan BASIC ($15/mois, 5 threads) suffit largement ; montez en threads seulement si vos jobs CI s'exécutent en forte concurrence.
CaptchaAI fonctionne-t-il si Better-Auth utilise hCaptcha ?
Non. CaptchaAI prend en charge reCAPTCHA v2/v3 et Cloudflare Turnstile, mais pas hCaptcha ni FunCaptcha (Arkose Labs). Configurez le plugin Better-Auth sur un fournisseur pris en charge pour vos environnements de test.
Comment garder l'intégration stable en production ?
Câblez les indicateurs ci-dessus dans vos tableaux de bord, plafonnez les retries à trois avec backoff exponentiel, et alertez sur l'écart entre réussite de résolution et acceptation en aval. Ces trois garde-fous suppriment la majorité des réveils nocturnes.
Puis-je transposer cette méthode à une autre pile ?
Oui. Le contrat envoyer/interroger est identique quel que soit le langage. Les exemples sont en Node.js, mais la même logique se porte vers Python, Go, Java ou tout écosystème compatible HTTP.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester vos CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution de CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos parcours de connexion automatisés avec une méthode reproductible. – Obtenez votre clé CaptchaAI.
