Stocker vos clés API CaptchaAI dans GCP Secret Manager

Périmètre sûr : Ce guide s'applique à vos propres applications — QA, préproduction, production — ou à des systèmes que vous êtes autorisé à tester, jamais à des sites tiers.

Stocker votre clé API CaptchaAI dans GCP Secret Manager change une chose : la valeur cesse de circuler avec le code, et sa lecture devient un droit IAM traçable. La mise en place tient en trois gestes : un secret dédié dans Secret Manager, le rôle roles/secretmanager.secretAccessor accordé au seul compte de service concerné, une lecture au démarrage.

Pourquoi Secret Manager plutôt qu'une variable d'environnement

Une variable définie dans la console Cloud Run reste lisible par tout compte ayant accès au service. Secret Manager sépare ce que la variable confond : la valeur du secret et le droit de la lire.

Pour des workers en europe-west9 (Paris), un seul secret alimente Cloud Run, Cloud Scheduler et les runners de tests.

Créer le secret et restreindre les droits IAM

Créer le secret et sa première version

1. Créez un secret au nom explicite, captchaai-api-key par exemple.
2. Gardez la réplication automatique, ou limitez-la aux régions européennes si votre politique l'exige.
3. Ajoutez la clé via gcloud secrets versions add, qui lit l'entrée standard : la valeur échappe à l'historique du shell.

Accorder le rôle au bon compte de service

Moindre privilège : roles/secretmanager.secretAccessor se pose sur le secret, pas sur le projet, et va au compte de service du worker.

Lire la clé au démarrage, pas à chaque appel

Chargez le secret une fois au démarrage et gardez-le en mémoire : un appel avant chaque résolution de CAPTCHA ajoute de la latence et pollue vos journaux d'audit. Prévoyez un rechargement contrôlé — signal SIGHUP ou cache à TTL court — pour absorber une rotation sans couper le trafic.

Encapsuler l'appel CaptchaAI dans une fonction réutilisable

Une seule fonction manipule la clé : elle prend le sitekey et l'URL de votre page, et retourne un token.

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 token obtenu reste à vérifier côté backend avant toute opération métier.

Faire tourner la clé sans couper le service

1. Ajoutez la nouvelle clé comme version supplémentaire, sans rien désactiver.
2. Laissez les workers la récupérer au redémarrage ou au rechargement contrôlé.
3. Vérifiez que le taux de réussite reste stable.
4. Désactivez l'ancienne version avant de la détruire : elle reste récupérable si un job de nuit la référence encore.
5. En production, épinglez un numéro de version plutôt que latest.

Journalisation, RGPD et audit des accès

Activez les journaux d'accès aux données de Secret Manager : vous saurez quel compte de service a lu quelle version, et quand. Corrélez-les à vos traces OpenTelemetry. La clé n'est pas une donnée personnelle, mais les journaux voisins en contiennent : URL, adresses IP, identifiants de session. Minimisez la collecte, fixez une rétention, vérifiez vos obligations RGPD.

Dépannage

Liste de contrôle avant mise en production

• Périmètre limité à vos applications ou à des sources autorisées.
• Clé CaptchaAI dans Secret Manager, jamais dans un fichier versionné.
• secretAccessor posé sur le secret, pour un compte de service dédié.
• Version épinglée en production, rotation documentée.
• Retry idempotent avec backoff borné.

FAQ

Quel rôle IAM faut-il donner exactement ?

roles/secretmanager.secretAccessor, posé sur le secret, pour le compte de service du worker. Réservez roles/secretmanager.admin à l'équipe infrastructure : il détruit aussi les versions.

Que se passe-t-il si je détruis une version encore utilisée ?

Les processus qui la référencent échouent au chargement. Désactivez-la vingt-quatre heures avant : sans lecture dans les journaux d'audit, la destruction est sans risque.

Une seule clé pour tous les environnements, est-ce acceptable ?

Non : un secret par environnement, avec des comptes de service distincts. La facture ne bouge pas, les plans CaptchaAI se comptant en threads simultanés — BASIC ($15/mois, 5 threads) suffit à une préproduction.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégration CAPTCHA en CI
• Résoudre reCAPTCHA v2 via API

Un secret bien rangé, une rotation documentée, et vos déploiements cessent d'être un pari. – Obtenez votre clé CaptchaAI.