---
title: API-Referenz
---

# API-Referenz

CaptchaLa stellt eine RESTful API für alle serverseitigen Integrationen bereit.

## Basis-URL

```
https://apiv1.captcha.la
```

## Authentifizierung

Alle API-Anfragen erfordern Authentifizierungs-Header:

```
X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

::: warning
`X-App-Secret` ist ausschließlich serverseitig. Geben Sie es niemals an Browser, mobile Apps oder öffentliche Repositories weiter.
:::

## Serverseitige Validierungs-API

> 💡 **Verwenden Sie ein Server-SDK, um sich den Boilerplate-Code zu sparen.** Es kapselt den Endpoint, kümmert sich um Retries und liefert typisierte Fehler:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php) ([中文](https://github.com/Captcha-La/captchala-php/blob/main/README_zh.md))
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://github.com/Captcha-La/captchala-go)

Nachdem der Nutzer das Frontend-CAPTCHA bestanden hat, muss Ihr Server den vom SDK zurückgegebenen Token validieren. Nachfolgend die serverseitigen Validierungs-Endpoints.

### Serverseitige Token-Validierung

Validieren Sie den pass_token aus dem Frontend-SDK (mit pt_-Präfix). Erfordert die Header X-App-Key und X-App-Secret.

```bash
POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }
```

`client_ip` ist **optional, aber empfohlen**: die IP des Endnutzers aus Ihrer eingehenden Anfrage, die für zusätzliche Risikoprüfungen verwendet wird. Sie können es problemlos weglassen.

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}
```

Das `captcha_args`-Objekt ist **rein informativ** (für Ihr Logging / Ihre Risikoanalyse):

| Feld | Beschreibung |
| --- | --- |
| `platform` | Plattform, von der die Challenge gelöst wurde. |
| `user_ip` | Zum Lösungszeitpunkt erfasste IP. |
| `referer` | Referer-URL der Challenge-Seite. |
| `pkg` | Paket-Identifier der App (mobil), falls zutreffend. |
| `solved_at` | Unix-Zeitstempel der Lösung. |
| `risk_score` | Risiko-Score der Lösungssitzung. |

::: tip
Prüfen Sie `data.valid === true` **und** dass `data.action` mit der erwarteten Szene übereinstimmt
(weisen Sie einen Token aus einem `pay`-Flow zurück, wenn er an `/login` präsentiert wird). Tokens sind Einmal-Tokens.
:::

## Servergenerierter Challenge-Token {#server-token}

Stellen Sie einen kurzlebigen server_token aus Ihrem Backend heraus aus. Der Browser übergibt diesen Token anschließend bei der Initialisierung einer Challenge und beweist damit, dass die Anfrage von Ihrem vertrauenswürdigen Server stammt.

### Server-Token ausstellen

Rufen Sie diesen Endpoint ausschließlich von Ihrem eigenen Server aus auf. Erfordert X-App-Key + X-App-Secret. Die Antwort enthält einen server_token (sct_-Präfix), den das Frontend an die Challenge-Initialisierung weiterreicht.

```bash
POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4
```

```json
{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}
```

#### Body-Parameter (form-urlencoded)

| Feld | Beschreibung |
| --- | --- |
| `action` | Business-Szene, z. B. login, register, pay. Muss mit der bei der Challenge-Initialisierung verwendeten action übereinstimmen. |
| `ttl` | Token-Lebensdauer in Sekunden. Standard 300, Maximum 900. |
| `max_uses` | Maximale Anzahl an Einlösungen des Tokens. Standard 10. |
| `bind_ip` | Bindet den Token an eine Client-IP. Eine Initialisierung von einer anderen IP wird abgewiesen. |
| `bind_device_id` | Bindet den Token an eine bestimmte Geräte-ID. |
| `bind_fingerprint` | Bindet den Token an einen bestimmten Browser-Fingerprint. |

### Challenge initialisieren

Wird vom SDK aufgerufen, um eine CAPTCHA-Challenge zu starten. Akzeptiert einen optionalen, von /v1/server/challenge/issue ausgestellten server_token.

| Feld | Beschreibung |
| --- | --- |
| `app_key` | Ihr öffentlicher App Key. |
| `action` | Business-Szene. Muss mit der beim Ausstellen des server_token verwendeten action übereinstimmen. |
| `server_token` | Optional; erforderlich, wenn für die Anwendung server_token_required = true gesetzt ist. |

::: info
Ist server_token_required für diese Anwendung im Dashboard aktiviert, weist die Challenge-Initialisierung Anfragen ohne gültigen server_token zurück.
:::

## Fehlercodes

| Code | Beschreibung |
| --- | --- |
| `invalid_app_key` | Ungültiger App Key |
| `invalid_app_secret` | Ungültiges App Secret |
| `challenge_expired` | Challenge abgelaufen |
| `challenge_not_found` | Challenge nicht gefunden |
| `invalid_answer` | Ungültige Antwort |
| `token_expired` | Token abgelaufen |
| `token_already_used` | Token bereits verwendet |
| `token_not_found` | Token nicht gefunden |
| `quota_exceeded` | Kontingent überschritten |
| `rate_limited` | Rate Limit erreicht |
| `rate_limit_exceeded` | Zu viele Ausstellungs-Anfragen für diese Anwendung. Bitte zurückfahren und erneut versuchen. |