Intégrer CaptchaAI à une Server Action Clerk

Périmètre sûr : Ce guide s'applique uniquement à vos propres applications et à vos environnements de développement, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne traite pas de l'automatisation de sites tiers ni du franchissement de protections anti-bot sur des services que vous ne contrôlez pas.

Une Server Action Clerk qui bute sur un CAPTCHA se débloque en récupérant un token via l'API CaptchaAI, puis en l'injectant dans la même requête serveur qui a déclenché le défi. L'enjeu est de rendre ce cycle prévisible : latence maîtrisée, échecs explicites, code lisible. Ce guide câble l'intégration côté serveur pour qu'elle tienne en production, pas seulement en démo.

Pourquoi coupler CaptchaAI à une Server Action Clerk

Clerk gère l'authentification, mais dès qu'un formulaire d'inscription ou de connexion est protégé par reCAPTCHA v2, reCAPTCHA v3 ou Cloudflare Turnstile, la Server Action reste bloquée tant que le défi n'est pas résolu. En exécution autonome — job planifié, worker interne ou chaîne CI — il faut une latence prévisible, des échecs propres et un code lisible. CaptchaAI répond avec une seule API pour toutes les familles prises en charge et une facturation au thread : la formule BASIC ($15/mois, 5 threads) suffit pour un flux d'inscription, et chaque thread offre des résolutions illimitées — la montée en charge dépend des threads, pas du volume.

Scénario réel : une inscription protégée par Turnstile

Prenez une application Next.js déployée sur Scaleway ou OVHcloud, avec une inscription gérée par Clerk. À la soumission du formulaire, un défi Cloudflare Turnstile s'affiche : votre Server Action reçoit le sitekey et l'URL de la page, appelle CaptchaAI pour obtenir un token, puis le transmet à la vérification côté serveur avant de créer le compte. L'intégration doit survivre aux fenêtres de déploiement et aux aléas réseau. Côté conformité RGPD, minimisez les données personnelles collectées avant de conserver le moindre identifiant.

Étapes d'intégration recommandées

Votre Server Action appelle CaptchaAI via HTTPS, récupère un token, puis l'injecte dans la vérification qui poursuit le flux. La séquence reste la même quel que soit le type de CAPTCHA :

1. Récupérez les paramètres exacts attendus par la famille de CAPTCHA (sitekey, URL de page, action éventuelle, proxy optionnel). Les paramètres superflus créent de fausses pistes de débogage.
2. Envoyez la tâche à l'API et récupérez son identifiant (taskId). Traitez toute réponse inattendue comme une erreur et journalisez-la.
3. Interrogez le résultat à intervalle régulier plutôt qu'en boucle serrée : attendez quelques secondes, puis interrogez toutes les cinq secondes avec un plafond ferme par tâche.
4. Injectez le token dans la même session que celle qui a déclenché le défi — même contexte serveur, même client HTTP, mêmes cookies. Une session incohérente est la première cause de rejet après résolution.
5. Mesurez la latence, les retries et l'acceptation, en distinguant réussite du solveur et du workflow.

Configuration des secrets

Traitez la clé CaptchaAI comme un secret strictement serveur :

• stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI ;
• montez-la en variable d'environnement au runtime, jamais dans un .env versionné ;
• dans une Server Action, elle ne transite jamais par le navigateur.

Exemple de code

Exemple d'appel HTTP côté serveur, à l'intérieur de votre propre service — ici la soumission d'une tâche Turnstile qui renvoie un taskId :

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;
}

Liste de contrôle avant la mise en production

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans un .env versionné.
• Les paramètres envoyés (sitekey, URL de page, action) correspondent au HTML réel de la page.
• Le token est injecté dans la même session serveur que celle qui a déclenché le défi.
• Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
• Les durées, codes HTTP et identifiants de tâche sont tracés ; les tests sont rejouables depuis votre CI.

Dépannage

Observabilité et journalisation

Instrumentez chaque appel CAPTCHA pour rendre l'intégration observable :

• métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente ;
• journaux séparés par environnement et corrélés à votre traçage distribué (OpenTelemetry, par exemple) ;
• suivi du taux de réussite du solveur et de l'acceptation de bout en bout : un token obtenu n'est pas un compte créé.

Côté RGPD, gardez ces journaux exempts de données personnelles — un identifiant de tâche et un horodatage suffisent.

FAQ

Où placer la clé API CaptchaAI dans une application Next.js avec Clerk ?

Côté serveur uniquement, jamais dans le bundle client. Chargez-la depuis une variable d'environnement injectée au runtime (secret CI, HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault). Dans une Server Action, la clé ne transite jamais par le navigateur ni n'apparaît dans le code client.

Faut-il résoudre le CAPTCHA côté serveur ou côté client ?

Côté serveur, dans la Server Action, pour garder la clé API secrète. Le sitekey et l'URL se lisent côté client, mais la soumission et l'interrogation du résultat restent serveur. Injectez ensuite le token dans la requête qui poursuit le flux, sans changer de session.

Comment gérer une erreur transitoire pendant une Server Action ?

Mettez en place un retry avec backoff exponentiel borné : trois tentatives, doublement du délai, plafond à 30 secondes. Tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez le réseau (DNS, certificats) et les quotas liés à votre clé.

CaptchaAI prend-il en charge hCaptcha si Clerk l'utilise ?

Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'OCR d'image et les grilles, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). Vérifiez la famille présentée par votre configuration Clerk avant l'intégration.

Guides connexes

• le démarrage rapide CaptchaAI
• la QA CAPTCHA en environnements autorisés
• tester l'endpoint API sur vos formulaires
• l'intégration CAPTCHA en chaîne CI
• résoudre reCAPTCHA v2 via l'API

Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.