Démarrage rapide

Ce guide vous aidera à intégrer le CAPTCHA CaptchaLa en 5 minutes.

Voyez-le fonctionner en 30 secondes

demo-v1.captcha.la — HTML + PHP pur, sous licence MIT, code source consultable sur chaque page.

• popup.html — mode popup
• float.html — widget flottant
• bind.html — lié à un bouton
• inline.html — intégration en ligne
• server-token.html — token émis par le serveur (anti-rejeu)

1. Créer un compte

Inscrivez-vous gratuitement dans le tableau de bord

S'inscrire maintenant →

2. Créer une application

Créez une application dans le tableau de bord pour obtenir votre App Key

3. Installer le SDK

Choisissez votre méthode d'installation préférée

<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# or via npm
npm install captchala

4. Initialiser le CAPTCHA

Initialisez le composant CAPTCHA dans votre page

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. Vérification côté serveur

Vérifiez le token sur votre serveur

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Vérifiez toujours que data.valid === true et que data.action correspond à la scène attendue. Les pass tokens sont à usage unique ; le même pt_xxx ne peut pas être validé deux fois.

Mode token émis par le serveur (recommandé en production)

Pour les actions sensibles (connexion, inscription, paiement), nous recommandons le flux de token émis par le serveur : votre backend demande d'abord un server_token à durée de vie courte, que le navigateur utilise ensuite pour initialiser le CAPTCHA. Cela empêche les abus liés à une fuite de l'app_key.

Quand l'utiliser

• Recommandé : inscription, connexion, réinitialisation de mot de passe, paiement, échange de points et tout endpoint qu'un attaquant peut scripter.
• Optionnel : formulaires publics occasionnels, champs de recherche et interactions à faible valeur où la commodité prime.

1. Le backend émet le server_token

Appelez /v1/server/challenge/issue depuis votre propre serveur, en utilisant les en-têtes X-App-Key et X-App-Secret. N'exposez jamais ces en-têtes au navigateur.

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. Le frontend affiche CaptchaLa avec le server_token

Transmettez le token à votre composant CaptchaLa. Le SDK le transmet à l'initialisation du challenge.

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

Notes de sécurité

• Ne placez jamais l'app_secret dans le code frontend, les applications mobiles ou les dépôts publics. Il doit rester côté serveur.
• Activez « Exiger un token de challenge émis par le serveur » dans le tableau de bord afin de rejeter tout challenge tenté sans server_token.
• Conservez un ttl court (300 s par défaut, 900 s maximum) et préférez max_uses=1 pour réduire l'impact d'une fuite de token.

Étapes suivantes

• SDK Web
• Référence de l'API