Périmètre sûr : ce guide s'applique exclusivement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'un dispositif anti-bot.
Une Auth0 Action est une fonction serverless qui s'exécute au cœur du pipeline d'authentification : après un login, avant la création d'un compte, ou pendant l'envoi d'un code. Lorsqu'un de ces parcours passe par une page protégée par un CAPTCHA, c'est CaptchaAI qui fournit le token attendu, et votre Action — ou le service qu'elle appelle — se charge de l'injecter au bon moment. L'enjeu n'est pas de faire fonctionner l'appel une fois dans un notebook, mais de le rendre assez stable pour tourner sans surveillance en CI, dans un cron ou une file d'attente interne.
Où CaptchaAI s'insère dans le pipeline Auth0
Une bonne règle : gardez l'Auth0 Action mince. Son runtime impose un budget de temps court, mal adapté à une résolution qui peut prendre plusieurs secondes. Déléguez donc l'appel à CaptchaAI à un composant interne — un worker ou un micro-service — que votre Action déclenche via HTTPS. Ce composant récupère le token, puis le renvoie à votre formulaire ou à votre route d'API.
Tracez chaque étape : c'est ce qui vous permettra de repérer une régression lors d'une montée de version d'Auth0 ou d'un changement de famille de CAPTCHA sur la page.
Gérer la clé API CaptchaAI
La clé CaptchaAI ne vit jamais dans le code source ni dans un dépôt versionné. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de votre chaîne CI. Côté Auth0, utilisez le stockage de secrets des Actions plutôt qu'une valeur en dur. Au déploiement, la clé est montée en variable d'environnement au runtime ; une rotation ne casse rien puisque aucun fichier suivi par Git ne la référence.
Le contrat submit/poll de l'API CaptchaAI
L'appel à CaptchaAI suit toujours le même contrat : vous soumettez une tâche, puis vous interrogez le résultat jusqu'à obtenir le token. L'exemple ci-dessous, en Node.js, montre la soumission d'une tâche Turnstile depuis votre propre service :
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;
}
Le même schéma vaut pour les autres familles prises en charge : vous changez le type de tâche, la boucle d'interrogation reste identique. Appliquez toujours 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 cookie jar. Une session qui ne correspond pas est la cause la plus fréquente d'un token refusé.
Observabilité et journalisation
Instrumentez les appels CAPTCHA pour alimenter vos tableaux de bord de QA et vos alertes avec des métriques exploitables :
- la durée totale d'obtention du token ;
- le code de retour HTTP et l'identifiant de tâche ;
- la taille de la file d'attente interne.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple avec OpenTelemetry, pour rejouer un parcours complet depuis un seul identifiant. Comme l'authentification manipule des données personnelles, appliquez le principe de minimisation du RGPD : ne journalisez ni identifiants, ni adresses e-mail, ni tokens en clair.
Mesurer ce qui compte
Distinguez deux réussites souvent confondues : la résolution du CAPTCHA et l'acceptation du parcours en aval. Une tâche résolue n'est pas un login réussi. Suivez au minimum ces trois indicateurs :
| Indicateur | Cible | Ce qu'il révèle |
|---|---|---|
| Latence d'obtention du token (médiane et P95) | Basse et stable dans le temps | Le pipeline n'attend pas sur des nouvelles tentatives. |
| Taux de réussite par famille de CAPTCHA | ≥ 95 % | Vos paramètres correspondent au défi réel de la page. |
| Taux d'acceptation après injection du token | Proche du taux de résolution | Un écart qui se creuse trahit une session qui ne correspond pas ou un token appliqué trop tard. |
Liste de contrôle avant la mise en production
- Le périmètre reste limité à vos propres applications ou à des sources autorisées par écrit.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code.
- La durée d'appel et le code de retour sont tracés à chaque exécution.
- Le token est injecté dans la même session que celle qui a déclenché le défi CAPTCHA.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, couvre les erreurs transitoires.
- Les tests sont rejouables depuis votre intégration continue, sans intervention manuelle.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou issue d'un autre compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret CI. |
ERROR_ZERO_BALANCE |
Solde du compte sous le minimum par tâche. | Rechargez le solde et ajoutez une alerte de solde bas sur votre tableau de bord. |
ERROR_BAD_PARAMETERS |
Un paramètre requis manque ou est mal formé. | Revalidez l'URL de la page et le sitekey face au HTML réel de la page. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Conservez la résolution et l'envoi du formulaire dans le même contexte ou la même session HTTP. |
FAQ
Une Auth0 Action peut-elle appeler CaptchaAI de façon synchrone ?
Mieux vaut l'éviter. Le runtime des Actions impose un budget de temps court, or une résolution peut demander plusieurs secondes. Déclenchez l'appel depuis un worker ou un service dédié, et laissez l'Action se contenter d'orchestrer l'appel ou de vérifier le résultat. Votre pipeline d'authentification reste ainsi réactif.
Où conserver la clé API CaptchaAI dans un environnement Auth0 ?
Dans le stockage de secrets des Actions ou dans votre coffre habituel (Vault, AWS Secrets Manager, Azure Key Vault), jamais en dur dans le code. La clé est ensuite montée en variable d'environnement au runtime, ce qui permet une rotation sans redéploiement.
Comment tester ce parcours sans toucher à la production ?
Rejouez-le en préproduction avec un locataire Auth0 de test et vos propres formulaires. Tracez chaque appel CAPTCHA, mesurez la latence et le taux de réussite, puis figez ces vérifications dans votre intégration continue. Le déroulé reste identique en Python, Node.js, Go ou tout autre écosystème compatible HTTP.
Quelle offre CaptchaAI pour un pipeline d'authentification à fort trafic ?
La facturation de CaptchaAI se fait au thread simultané, avec un nombre de résolutions illimité par thread. Un pipeline d'authentification est borné par sa concurrence, pas par un volume quotidien : dimensionnez l'offre sur le nombre de tâches en vol. L'offre BASIC ($15/mois, 5 threads) couvre un flux modéré ; montez en gamme si votre concurrence dépasse ce seuil.
Guides connexes
- Démarrage rapide avec CaptchaAI
- Tester vos CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires web
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Rendez vos workflows CAPTCHA reproductibles et faciles à diagnostiquer. – Obtenez votre clé CaptchaAI.
