---
title: Démarrage rapide
---

# Démarrage rapide

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

::: tip Voyez-le fonctionner en 30 secondes
[demo-v1.captcha.la](https://demo-v1.captcha.la) — HTML + PHP pur, sous licence MIT, code source consultable sur chaque page.

- [popup.html](https://demo-v1.captcha.la/popup.html) — mode popup
- [float.html](https://demo-v1.captcha.la/float.html) — widget flottant
- [bind.html](https://demo-v1.captcha.la/bind.html) — lié à un bouton
- [inline.html](https://demo-v1.captcha.la/inline.html) — intégration en ligne
- [server-token.html](https://demo-v1.captcha.la/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 →](https://dash.captcha.la/register)

## 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

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

```bash
# or via npm
npm install captchala
```

## 4. Initialiser le CAPTCHA

Initialisez le composant CAPTCHA dans votre page

```html
<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

```bash
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>" }
```

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "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) {#server-token}

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.

```bash
# 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.

```js
// 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](./web-sdk)
- [Référence de l'API](./api-reference)