Périmètre sûr : ce guide couvre vos propres applications et vos environnements de test, de préproduction ou de production, ainsi que les systèmes pour lesquels vous détenez une autorisation écrite. Il ne décrit pas l'automatisation de sites tiers.
Une clé API CaptchaAI n'a rien à faire dans un fichier .env suivi par Git. La réponse tient en une ligne : gardez-la dans Bitwarden Secrets Manager et injectez-la au moment de l'exécution, pour qu'elle n'atterrisse jamais sur le disque d'un agent CI.
Pourquoi votre clé CaptchaAI mérite un coffre
Une clé CaptchaAI ouvre l'accès à un solde et à une capacité de threads facturée au mois : le premier palier, BASIC ($15/mois, 5 threads), suffit à un pipeline de QA, mais une clé qui fuite consomme votre capacité. Un fichier de configuration commité, un log verbeux qui recopie le payload, et le secret circule hors de tout contrôle.
Le coffre apporte surtout un point unique de rotation : une seule valeur à changer, pas quinze jobs, et un audit lisible côté RGPD.
Modéliser le secret côté Bitwarden
Bitwarden Secrets Manager organise les valeurs en projets et les accès en machine accounts. Un machine account reçoit un jeton et une portée limitée aux projets dont il a besoin : le modèle attendu pour un runner. Une découpe qui vieillit bien :
- Un projet par environnement (
captchaai-staging,captchaai-prod), jamais un projet fourre-tout. - Un machine account par pipeline, en lecture seule sur le projet correspondant.
- Le secret nommé sans ambiguïté,
CAPTCHAAI_API_KEY, avec une note indiquant le compte concerné.
Le jeton du machine account (BWS_ACCESS_TOKEN) devient le seul élément à déclarer dans votre CI : un secret bootstrap révocable, au lieu d'une clé métier disséminée.
Injecter la clé au moment de l'exécution
Le CLI bws lit ce jeton, récupère la valeur et la passe au processus enfant. L'étape CI se réduit à une commande qui enveloppe votre script de test et expose CAPTCHAAI_KEY le temps de ce processus : rien n'est écrit sur disque, rien ne survit au job.
Scénario courant côté francophone : une équipe QA lyonnaise exécute ses tests de bout en bout sur des runners GitLab CI auto-hébergés chez OVHcloud, avec un machine account distinct pour la préproduction et pour la production. Quand un prestataire quitte le projet, un jeton est révoqué et aucun pipeline n'est modifié.
Appeler l'API avec la clé injectée
L'exemple ci-dessous encapsule la soumission d'une tâche Turnstile : elle prend le sitekey et l'URL de votre page, et retourne l'identifiant de tâche à interroger.
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;
}
Gardez-la comme seul point d'entrée vers CaptchaAI : un seul endroit lit process.env, un seul endroit à auditer.
Vérifier le token côté backend
Le token doit être validé par votre backend avant toute opération métier : cela empêche qu'une requête soit acceptée sur la foi d'un token expiré ou rejoué. Appliquez-le dans la session qui a déclenché le défi CAPTCHA, avec les mêmes cookies.
Journaliser sans exposer le secret
Instrumentez les appels, mais choisissez ce que vous écrivez. Utile : la durée d'obtention du token, le code retour HTTP, l'identifiant de tâche. À proscrire : le payload complet, la clé même tronquée, et toute donnée personnelle captée au passage — la minimisation RGPD vaut aussi pour les logs techniques.
Liste de contrôle avant la mise en production
- La clé n'existe que dans Bitwarden Secrets Manager, jamais dans le dépôt.
- Chaque pipeline a son machine account, en lecture seule sur un seul projet.
- Le jeton d'accès est renouvelé selon un calendrier écrit.
- Les logs tracent des durées et des codes retour, jamais de secret.
- Un retry avec backoff exponentiel borné couvre les erreurs transitoires.
FAQ
Faut-il un projet Bitwarden distinct par environnement ?
Oui, et c'est ce qui évite le plus d'incidents : un runner de préproduction obtient alors un accès qui ne débloque rien en production. La séparation coûte cinq minutes.
Comment faire tourner la clé sans casser les pipelines en cours ?
Créez la nouvelle clé dans le tableau de bord CaptchaAI, mettez à jour la valeur dans le coffre, laissez les jobs en cours se terminer, puis révoquez l'ancienne : aucun redéploiement.
Que se passe-t-il si le jeton du machine account fuite ?
Révoquez-le depuis Bitwarden : il ne donne accès qu'aux projets attribués et la clé CaptchaAI reste inchangée. C'est l'intérêt du secret bootstrap — le rayon d'impact est connu d'avance.
Et hors CI, sur un worker de longue durée ?
Le worker lit la variable à son démarrage ; prévoyez un rechargement à la rotation, par redémarrage progressif ou relecture périodique.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA à votre CI
- Résoudre reCAPTCHA v2 via l'API
Un secret bien rangé, c'est une astreinte de moins. – Obtenez votre clé CaptchaAI.
