Gérer la clé API CaptchaAI avec Infisical

Périmètre sûr : ce guide s'applique à vos propres applications et environnements (QA, préproduction, production) ou à des systèmes pour lesquels vous avez une autorisation écrite. Il ne traite pas de l'automatisation de sites tiers.

Une clé API CaptchaAI oubliée dans un .env versionné, et votre solde finance les appels de quelqu'un d'autre. La règle est simple : la clé n'existe que dans un coffre, qu'Infisical distribue à vos scripts, conteneurs et jobs CI à l'exécution. Voici le circuit complet, du projet jusqu'à la rotation.

Pourquoi sortir la clé API CaptchaAI du dépôt

Une clé CaptchaAI ouvre l'accès à un solde et à des threads facturés : sur un plan BASIC ($15/mois, 5 threads), une fuite sature aussitôt la capacité de vos tests. Elle circule aussi sur le poste du développeur, les runners CI et des workers planifiés — autant d'endroits où elle finit en clair.

Infisical apporte une source unique, des environnements séparés (dev, staging, prod) aux droits distincts, et un journal d'accès.

Étape 1 : créer le projet et les environnements

Créez un projet Infisical dédié à votre automatisation, puis un secret CAPTCHAAI_KEY par environnement. Des clés distinctes sont la seule façon de mesurer la consommation de vos tests sans fausser les métriques de production.

Étape 2 : injecter le secret à l'exécution

En local comme en conteneur, infisical run -- <commande> expose les secrets en variables d'environnement, sans rien écrire sur le disque. Dans un pipeline, l'authentification passe par une identité machine et le token expire avec le job. Votre code ne connaît que process.env.CAPTCHAAI_KEY : aucune valeur en dur, aucun fichier à nettoyer avant un commit.

Étape 3 : encapsuler l'appel CaptchaAI

Isolez l'appel dans une fonction unique : un seul endroit à corriger quand la clé change, un seul à instrumenter.

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

Étape 4 : vérifier le token côté backend

Validez le token côté serveur avant toute opération métier : le solveur produit une preuve, votre backend décide de sa validité.

Rotation et RGPD : le cas d'une agence lyonnaise

Prenons une agence lyonnaise qui exploite des suites de tests pour plusieurs clients : workers chez Scaleway et OVHcloud, runners partagés, et une clé à régénérer dans quatre dépôts à chaque départ de prestataire. Avec Infisical, la rotation tient en trois gestes — nouvelle valeur dans le coffre, redémarrage des workers, ancienne clé révoquée depuis le tableau de bord CaptchaAI. Planifiez-la tous les 90 jours.

Côté RGPD, la clé n'est pas une donnée personnelle ; ce sont vos journaux qui méritent l'attention : n'y consignez ni URL de formulaire renseignée par un utilisateur, ni identifiant de compte.

Journaliser sans laisser fuiter la clé API CaptchaAI

Tracez chaque appel avec le temps de résolution, le code retour HTTP, l'identifiant de tâche et l'environnement : ces quatre champs suffisent à rejouer un incident. Ajoutez un filtre qui masque toute chaîne au format de la clé avant l'envoi au collecteur, puis corrélez avec votre traçage distribué (OpenTelemetry).

Liste de contrôle avant la mise en production

1. Aucune clé API CaptchaAI dans le dépôt, l'historique Git ou les fichiers de configuration.
2. Des clés distinctes pour dev, staging et prod.
3. La lecture de prod réservée à une identité machine.
4. Le format de la clé masqué dans les logs.
5. Une rotation planifiée au calendrier de l'équipe.
6. Un retry avec backoff exponentiel borné.

FAQ

Infisical est-il obligatoire pour appeler l'API CaptchaAI ?

Non. HashiCorp Vault ou AWS Secrets Manager conviennent aussi. Infisical se distingue par infisical run, qui supprime l'étape « écrire un fichier .env » que les équipes oublient de nettoyer.

Comment renouveler la clé sans interrompre les jobs en cours ?

Publiez la nouvelle clé dans le coffre, laissez les workers la récupérer au redémarrage suivant, puis révoquez l'ancienne. Quelques minutes de recouvrement suffisent à absorber les tâches déjà lancées.

Où stocker la clé pour un job planifié chez OVHcloud ou Scaleway ?

Dans le coffre, jamais dans la définition du cron. Lancez la tâche via une identité machine : le secret vit dans l'environnement du processus et disparaît avec lui.

Que faire si l'API renvoie une erreur transitoire ?

Trois tentatives au maximum, doublement du délai, plafond à 30 secondes. Si l'erreur persiste, vérifiez le solde et la clé avant de soupçonner le réseau.

Guides connexes

• Le démarrage rapide CaptchaAI
• Tester les CAPTCHA en environnement autorisé
• Vérifier 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é.