Schnellstart

Diese Anleitung hilft Ihnen, CaptchaLa CAPTCHA in 5 Minuten zu integrieren.

In 30 Sekunden in Aktion sehen

demo-v1.captcha.la — reines HTML + PHP, MIT-lizenziert, Quelltext auf jeder Seite einsehbar.

• popup.html — Popup-Modus
• float.html — schwebendes Widget
• bind.html — an Button binden
• inline.html — Inline-Einbettung
• server-token.html — servergenerierter Token (Anti-Replay)

1. Konto erstellen

Registrieren Sie sich kostenlos im Dashboard.

Jetzt registrieren →

2. Anwendung anlegen

Legen Sie im Dashboard eine Anwendung an, um Ihren App Key zu erhalten.

3. SDK installieren

Wählen Sie Ihre bevorzugte Installationsmethode.

<!-- 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. CAPTCHA initialisieren

Initialisieren Sie die CAPTCHA-Komponente auf Ihrer Seite.

<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. Serverseitige Validierung

Validieren Sie den Token auf Ihrem Server.

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

Prüfen Sie stets, dass data.valid === true und dass data.action mit der erwarteten Szene übereinstimmt. Pass-Tokens sind Einmal-Tokens; derselbe pt_xxx kann nicht zweimal validiert werden.

Servergenerierter-Token-Modus (für die Produktion empfohlen)

Für sensible Aktionen (Anmeldung, Registrierung, Bezahlung) empfehlen wir den servergenerierten Token-Flow: Ihr Backend fordert zunächst einen kurzlebigen server_token an, den der Browser anschließend zur Initialisierung des CAPTCHA verwendet. Dies verhindert Missbrauch durch einen geleakten app_key.

Wann sollte er verwendet werden?

• Empfohlen: Registrierung, Anmeldung, Passwort-Zurücksetzen, Bezahlung, Punkte-Einlösung sowie jeder Endpoint, den ein Angreifer skripten kann.
• Optional: einfache öffentliche Formulare, Suchfelder und geringwertige Interaktionen, bei denen Komfort wichtiger ist.

1. Backend stellt server_token aus

Rufen Sie /v1/server/challenge/issue von Ihrem eigenen Server aus auf, unter Verwendung der Header X-App-Key und X-App-Secret. Geben Sie diese Header niemals an den Browser weiter.

# 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. Frontend rendert CaptchaLa mit dem server_token

Übergeben Sie den Token an Ihre CaptchaLa-Komponente. Das SDK reicht ihn bei der Initialisierung der Challenge weiter.

// 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));

Sicherheitshinweise

• Geben Sie app_secret niemals in Frontend-Code, mobilen Apps oder öffentlichen Repositories preis. Es muss serverseitig bleiben.
• Aktivieren Sie im Dashboard "Servergenerierten Challenge-Token erforderlich", um jede Challenge ohne server_token abzulehnen.
• Halten Sie ttl kurz (Standard 300 s, max. 900 s) und bevorzugen Sie max_uses=1, um die Auswirkungen eines Token-Leaks zu minimieren.

Nächste Schritte

• Web-SDK
• API-Referenz