# CaptchaLa — Full documentation for LLMs

> CaptchaLa is a bot-protection platform: smart CAPTCHA, human verification, and content-moderation APIs that stop credential stuffing, scraping, fake signups, and spam across web, mobile, and desktop apps. Free tier: 10,000 verifications/month.

This file inlines the full developer documentation so an LLM can answer integration questions without fetching individual pages. Challenge types: slider, click, rotate, 3D click, text, image (47 UI languages). Native SDKs: Web (JS), React, Vue, iOS, Android, Flutter, Electron, server-side PHP and Go.

- Marketing: https://captcha.la
- Dashboard & API keys: https://dash.captcha.la
- GitHub (open-source SDKs): https://github.com/Captcha-La
- Contact: supply@captcha.la

The standard flow: render the widget on the client → receive a one-time token → POST it to your server → verify with your secret key via the API or a server SDK.

---



<!-- Source: https://docs.captcha.la/ -->

# Welcome to CaptchaLa

CaptchaLa provides smart CAPTCHA and content moderation API services. With simple SDK integration, you can add security protection to your apps in minutes.

::: tip See it work in 30 seconds
[demo-v1.captcha.la](https://demo-v1.captcha.la) — pure HTML + PHP, MIT-licensed, view-source on every page.

- [popup.html](https://demo-v1.captcha.la/popup.html) — popup mode
- [float.html](https://demo-v1.captcha.la/float.html) — floating widget
- [bind.html](https://demo-v1.captcha.la/bind.html) — bind to button
- [inline.html](https://demo-v1.captcha.la/inline.html) — inline embed
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — server-issued token (anti-replay)
:::


## Quick Links

- **[5-Minute Quickstart](./quickstart)** — This guide will help you integrate CaptchaLa CAPTCHA in 5 minutes.
- **[Web SDK Guide](./web-sdk)** — Web SDK supports all modern browsers with multiple integration methods.
- **[API Reference](./api-reference)** — CaptchaLa provides RESTful API for all server-side integrations.

## SDK Docs

- [Web SDK](./web-sdk)
- [Android SDK](./sdk/android)
- [iOS / macOS SDK](./sdk/ios)
- [Flutter SDK](./sdk/flutter)
- [Electron SDK](./sdk/electron)

## Security Modes

- **[Server-issued Token — Quick Start](./quickstart#server-token)** — Architecture and code samples for the backend-first token flow used in production.
- **[Server-issued Token — API Reference](./api-reference#server-token)** — POST /v1/server/challenge/issue — parameters, response schema, and error codes.



<!-- Source: https://docs.captcha.la/quickstart -->

# Quickstart

This guide will help you integrate CaptchaLa CAPTCHA in 5 minutes.

::: tip See it work in 30 seconds
[demo-v1.captcha.la](https://demo-v1.captcha.la) — pure HTML + PHP, MIT-licensed, view-source on every page.

- [popup.html](https://demo-v1.captcha.la/popup.html) — popup mode
- [float.html](https://demo-v1.captcha.la/float.html) — floating widget
- [bind.html](https://demo-v1.captcha.la/bind.html) — bind to button
- [inline.html](https://demo-v1.captcha.la/inline.html) — inline embed
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — server-issued token (anti-replay)
:::


## 1. Create Account

Sign up for a free account in the dashboard

[Sign Up Now →](https://dash.captcha.la/register)

## 2. Create Application

Create an app in the dashboard to get your App Key

## 3. Install SDK

Choose your preferred installation method

```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. Initialize CAPTCHA

Initialize the CAPTCHA component in your 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. Server Verification

Verify the token on your server

```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>", "client_ip": "<end-user IP>" }
```

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

::: warning
Always check `data.valid === true` **and** `data.action` matches the scene you expected.
Pass tokens are single-use; the same `pt_xxx` cannot be validated twice.
:::

## Server-issued Token Mode (recommended for production) {#server-token}

For sensitive actions (login, register, payment) we recommend the server-issued token flow: your backend first requests a short-lived server_token, which the browser then uses to initialize the CAPTCHA. This prevents abuse from a leaked app_key.

### When to use

- Recommended: register, login, password reset, payment, points redemption, and any endpoint an attacker can script.
- Optional: casual public forms, search boxes, and low-value interactions where convenience matters more.

### 1. Backend issues server_token

Call /v1/server/challenge/issue from your own server, using the X-App-Key and X-App-Secret headers. Never expose these headers to the browser.

```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. Frontend renders CaptchaLa with the server_token

Pass the token to your CaptchaLa component. The SDK forwards it to the challenge initialization when initializing the 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));
```

### Security notes

- Never put app_secret in frontend code, mobile apps, or public repositories. It must stay server-side.
- Enable "Require server-issued challenge token" in the dashboard to reject any challenge attempted without a server_token.
- Keep ttl short (300s default, 900s max) and prefer max_uses=1 to reduce the impact of token leakage.

## Next steps

- [Web SDK](./web-sdk)
- [API Reference](./api-reference)



<!-- Source: https://docs.captcha.la/web-sdk -->

# Web SDK

Web SDK supports all modern browsers with multiple integration methods.

::: tip See it work in 30 seconds
[demo-v1.captcha.la](https://demo-v1.captcha.la) — pure HTML + PHP, MIT-licensed, view-source on every page.

- [popup.html](https://demo-v1.captcha.la/popup.html) — popup mode
- [float.html](https://demo-v1.captcha.la/float.html) — floating widget
- [bind.html](https://demo-v1.captcha.la/bind.html) — bind to button
- [inline.html](https://demo-v1.captcha.la/inline.html) — inline embed
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — server-issued token (anti-replay)
:::

## Quick start

```html
<!-- 1. Load via CDN (or npm install captchala) -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

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

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(res => sendToBackend(res.token))
  .onError(err => console.error(err.message))
  .bindTo('#login-btn');
});
</script>
```

## Installation

### CDN

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

### NPM

```bash
npm install captchala
# or framework wrappers
npm install @captcha-la/vue
npm install @captcha-la/react
```

```js
import Captchala from 'captchala';
import 'captchala/dist/captchala.css';
```

## Modes

### Popup Mode

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'popup', action: 'login' })
  .bindTo('#login-btn')
  .onSuccess(res => sendToBackend(res.token));
```

### Float Mode

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'float', action: 'browse' })
  .appendTo('#captcha-container')
  .onSuccess(res => sendToBackend(res.token));
```

### Bind Mode

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'bind', action: 'login' })
  .bindTo('#submit-button')
  .onSuccess(res => submitForm(res.token));   // fires only after challenge passes
```

### Embed Mode

```js
Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'embed', action: 'register' })
  .appendTo('#captcha-container')
  .onSuccess(res => sendToBackend(res.token));
```

## Common options

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `appKey` | string | — | Application Key (required) |
| `product` | string | `popup` | Display mode: popup | float | embed | bind |
| `action` | string | `default` | Business scene (e.g. login, register, pay). The server applies different security policies per scene. |
| `lang` | string | `auto` | BCP-47 tag (e.g. `en`, `ja`, `pt-BR`) or `auto` to follow `navigator.language`. See [Supported languages](/supported-languages) — 54 locales. |
| `serverToken` | string | — | Single-use token (sct_xxx) issued by your server. Strongly recommended in production — prevents unbounded challenge refresh abuse. |
| `onServerTokenExpired` | `() => Promise<string>` | — | Called when serverToken expires; return a new one so SDK can continue without interrupting the flow. |
| `enableVoice` | boolean | `true` | Show the audio-captcha entry point (accessibility support for visually impaired users). |

## Server-side validation

After `onSuccess`, send `res.token` (prefix `pt_`) to your own backend, then validate it server-side:

```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": "<token>", "client_ip": "<end-user IP>" }
```

See the [API Reference](./api-reference) for the full validation endpoint.



<!-- Source: https://docs.captcha.la/api-reference -->

# API Reference

CaptchaLa provides RESTful API for all server-side integrations.

## Base URL

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

## Authentication

All API requests require authentication headers:

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

::: warning
`X-App-Secret` is server-side only. Never expose it to browsers, mobile apps, or public repos.
:::

## Server-side Validation API

> 💡 **Use a server SDK to skip the boilerplate.** Wraps the endpoint, handles retries, surfaces typed errors:
> - **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)

After user passes the frontend CAPTCHA, your server needs to validate the token returned by SDK. Below are the server-side validation endpoints.

### Server-side Token Validation

Validate pass_token from frontend SDK (with pt_ prefix). Requires X-App-Key and X-App-Secret headers.

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

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

::: tip
Validate `data.valid === true` **and** that `data.action` matches the scene you expected
(reject if a token from a `pay` flow is presented at `/login`). Tokens are single-use.
:::

### Token Types

The SDK may hand your frontend different token types depending on service conditions. The prefix tells you everything:

| Prefix | Issued when | `/v1/validate` returns | Recommended handling |
| --- | --- | --- | --- |
| `pt_` | Verification passed normally | `valid: true` (single-use) | Accept |
| `dg_` | Plan quota exhausted (degraded mode) | `valid: false`, `degraded: true`, `reason` | Your decision — see below |
| `offline_` | Main API unreachable; issued by the bypass worker | Verified against the backup API automatically when using a server SDK | Accept after backup verification |
| `co_` | Main **and** backup unreachable; generated client-side | Cannot be verified server-side | Apply your own risk controls (rate limits, etc.) |

### Degraded Mode (quota exhausted) {#degraded-mode}

When an app has exhausted its monthly quota (and overage billing is not available), the widget does **not** interrupt your end-user flow. Instead of showing an error, the SDK completes immediately with a `dg_` token:

- The end user sees no error — your form submits normally.
- Your server's `/v1/validate` returns:

```json
{
  "code": 0,
  "data": {
    "valid": false,
    "degraded": true,
    "reason": "quota_exhausted",
    "expired": false
  }
}
```

Key properties:

- `valid` is **always `false`** for degraded tokens — secure by default. If your code only checks `valid`, nothing changes for you.
- Whether to let the request through is **your decision**: accept `valid || degraded` to keep conversions flowing while you upgrade your plan, or reject and show your own fallback.
- `dg_` tokens are HMAC-signed per app and expire after 5 minutes. Issuing them costs no quota and is never billed.
- Server SDKs expose this as `isDegraded()` / `getDegradedReason()` (PHP) and `result.Degraded` / `result.DegradedReason` (Go).

::: info
Expired subscriptions never trigger degraded mode — they automatically fall back to the Free plan and keep serving within the free quota. Degraded mode only covers usage beyond your plan's quota.
:::

## Server-issued Challenge Token {#server-token}

Issue a short-lived server_token from your backend. The browser then passes this token when initializing a challenge, proving the request originated from your trusted server.

### Issue Server Token

Call this endpoint from your own server only. Requires X-App-Key + X-App-Secret. Response contains a server_token (sct_ prefix) that the frontend forwards to the challenge initialization.

```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 Parameters (form-urlencoded)

| Field | Description |
| --- | --- |
| `action` | Business scene, e.g. login, register, pay. Must match the action used in the challenge initialization. |
| `ttl` | Token lifetime in seconds. Default 300, max 900. |
| `max_uses` | Maximum times the token may be consumed. Default 10. |
| `bind_ip` | Bind token to a client IP. Initialization from another IP is rejected. |
| `bind_device_id` | Bind token to a specific device id. |
| `bind_fingerprint` | Bind token to a specific browser fingerprint. |

### Initialize Challenge

Called by the SDK to start a CAPTCHA challenge. Accepts an optional server_token issued by /v1/server/challenge/issue.

| Field | Description |
| --- | --- |
| `app_key` | Your public App Key. |
| `action` | Business scene. Must match the action used when issuing the server_token. |
| `server_token` | Optional; required when the app has server_token_required = true. |

::: info
If server_token_required is enabled for this app in the dashboard, the challenge initialization will reject requests that do not carry a valid server_token.
:::

## Error Codes

| Code | Description |
| --- | --- |
| `invalid_app_key` | Invalid App Key |
| `invalid_app_secret` | Invalid App Secret |
| `challenge_expired` | Challenge expired |
| `challenge_not_found` | Challenge not found |
| `invalid_answer` | Invalid answer |
| `token_expired` | Token expired |
| `token_already_used` | Token already used |
| `token_not_found` | Token not found |
| `quota_exceeded` | Quota exceeded |
| `rate_limited` | Rate limited |
| `rate_limit_exceeded` | Too many issuance requests for this app. Back off and retry. |



<!-- Source: https://docs.captcha.la/supported-languages -->

# Supported languages

Default `lang: 'auto'` follows the browser language. Pass an explicit BCP-47 tag (e.g. `'ja'`, `'pt-BR'`) to lock the widget. **54 locales shipped:**

| Tag | Native | Language |
| --- | --- | --- |
| `ar` | العربية | Arabic |
| `bg` | Български | Bulgarian |
| `bn` | বাংলা | Bengali |
| `cs` | Čeština | Czech |
| `da` | Dansk | Danish |
| `de` | Deutsch | German |
| `el` | Ελληνικά | Greek |
| `en` | English | English |
| `es` | Español | Spanish |
| `et` | Eesti | Estonian |
| `fa` | فارسی | Persian |
| `fi` | Suomi | Finnish |
| `fil` | Filipino | Filipino |
| `fr` | Français | French |
| `gu` | ગુજરાતી | Gujarati |
| `he` | עברית | Hebrew |
| `hi` | हिन्दी | Hindi |
| `hr` | Hrvatski | Croatian |
| `hu` | Magyar | Hungarian |
| `id` | Bahasa Indonesia | Indonesian |
| `it` | Italiano | Italian |
| `ja` | 日本語 | Japanese |
| `km` | ខ្មែរ | Khmer |
| `kn` | ಕನ್ನಡ | Kannada |
| `ko` | 한국어 | Korean |
| `lo` | ລາວ | Lao |
| `ml` | മലയാളം | Malayalam |
| `mr` | मराठी | Marathi |
| `ms` | Bahasa Melayu | Malay |
| `my` | မြန်မာ | Burmese |
| `ne` | नेपाली | Nepali |
| `nl` | Nederlands | Dutch |
| `no` | Norsk | Norwegian |
| `pa` | ਪੰਜਾਬੀ | Punjabi |
| `pl` | Polski | Polish |
| `pt` | Português | Portuguese |
| `pt-BR` | Português (Brasil) | Portuguese (Brazil) |
| `ro` | Română | Romanian |
| `ru` | Русский | Russian |
| `si` | සිංහල | Sinhala |
| `sk` | Slovenčina | Slovak |
| `sl` | Slovenščina | Slovenian |
| `sr` | Српски | Serbian |
| `sv` | Svenska | Swedish |
| `sw` | Kiswahili | Swahili |
| `ta` | தமிழ் | Tamil |
| `te` | తెలుగు | Telugu |
| `th` | ไทย | Thai |
| `tr` | Türkçe | Turkish |
| `uk` | Українська | Ukrainian |
| `ur` | اردو | Urdu |
| `vi` | Tiếng Việt | Vietnamese |
| `zh-CN` | 简体中文 | Simplified Chinese |
| `zh-TW` | 繁體中文 | Traditional Chinese |

RTL: `ar`, `fa`, `he`, `ur`. Region suffixes normalize via prefix match (`en-US` → `en`, `fr-CA` → `fr`).



<!-- Source: https://docs.captcha.la/sdk/react -->

# React SDK

Official React component + hook for CaptchaLa CAPTCHA — published as [`@captcha-la/react`](https://www.npmjs.com/package/@captcha-la/react).

## Live demo

::: tip 📦
[demo-v1.captcha.la/react](https://demo-v1.captcha.la/react/) — runnable demo with all four product modes.
Source: [Captcha-La/react-example](https://github.com/Captcha-La/react-example).
:::

## Install

```bash
npm install @captcha-la/react
# or
yarn add @captcha-la/react
# or
pnpm add @captcha-la/react
```

Peer dependencies: `react@^17 || ^18 || ^19`, `react-dom@^17 || ^18 || ^19`.

## Quick start

### Component

```tsx
import { Captchala } from '@captcha-la/react'

function App() {
  return (
    <Captchala
      appKey="your-app-key"
      product="popup"
      onSuccess={(result) => console.log('pass_token:', result.token)}
      onError={(err) => console.error(err)}
    />
  )
}
```

### Hook

```tsx
import { useCaptchala } from '@captcha-la/react'

function LoginForm() {
  const { ready, verify } = useCaptchala({
    appKey: 'your-app-key',
    product: 'bind',
    action: 'login',
  })

  async function handleSubmit(e) {
    e.preventDefault()
    const result = await verify()
    // result.token → submit with the form
  }

  return (
    <form onSubmit={handleSubmit}>
      <button type="submit" disabled={!ready}>Login</button>
    </form>
  )
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `appKey` | `string` | *required* | CaptchaLa application key |
| `serverToken` | `string` | - | One-time, server-issued challenge token. Required when the app has `server_token_required=true`. |
| `product` | `'popup' \| 'float' \| 'embed' \| 'bind'` | `'popup'` | Display mode |
| `action` | `string` | `'default'` | Action identifier |
| `lang` | `string` | `'zh-CN'` | Language code |
| `onSuccess` | `(result) => void` | - | Success callback |
| `onError` | `(error) => void` | - | Error callback |
| `onClose` | `() => void` | - | Close callback |
| `onReady` | `() => void` | - | Ready callback |
| `className` | `string` | - | Container class name |
| `style` | `CSSProperties` | - | Container inline styles |

## Methods (via `ref`)

```tsx
import { useRef } from 'react'
import { Captchala, type CaptchalaRef } from '@captcha-la/react'

function App() {
  const ref = useRef<CaptchalaRef>(null)
  return (
    <>
      <Captchala ref={ref} appKey="your-app-key" />
      <button onClick={() => ref.current?.verify()}>Verify</button>
    </>
  )
}
```

| Method | Description |
|--------|-------------|
| `verify()` | Trigger verification |
| `reset()` | Reset CAPTCHA state |
| `destroy()` | Destroy the instance |
| `bindTo(selector)` | Bind to element (for `bind` mode) |
| `setLang(lang)` | Switch language in place |

## Production: `serverToken` mode

```tsx
import { useState, useEffect } from 'react'
import { Captchala } from '@captcha-la/react'

function LoginPage() {
  const [token, setToken] = useState<string>()

  useEffect(() => {
    fetch('/api/captcha-token')         // your own backend
      .then((r) => r.json())
      .then((d) => setToken(d.server_token))
  }, [])

  if (!token) return <div>Loading…</div>

  return (
    <Captchala
      serverToken={token}
      appKey="pk_your_public_app_key"
      action="login"
      onSuccess={(r) => console.log('pass_token:', r.token)}
    />
  )
}
```

See [API Reference](/api-reference) for the full backend contract.

## Links

- [npm](https://www.npmjs.com/package/@captcha-la/react) · [GitHub](https://github.com/Captcha-La/react) · [example](https://github.com/Captcha-La/react-example)
- [Web SDK overview](/web-sdk) · [API Reference](/api-reference)



<!-- Source: https://docs.captcha.la/sdk/vue -->

# Vue SDK

Official Vue 3 component for CaptchaLa CAPTCHA — published as [`@captcha-la/vue`](https://www.npmjs.com/package/@captcha-la/vue).

## Live demo

::: tip 📦
[demo-v1.captcha.la/vue](https://demo-v1.captcha.la/vue/) — runnable demo with all four product modes.
Source: [Captcha-La/vue-example](https://github.com/Captcha-La/vue-example).
:::

## Install

```bash
npm install @captcha-la/vue
# or
yarn add @captcha-la/vue
# or
pnpm add @captcha-la/vue
```

Peer dependency: `vue@^3.2.0`.

## Quick start

```vue
<template>
  <Captchala
    app-key="your-app-key"
    product="popup"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { Captchala } from '@captcha-la/vue'

function handleSuccess(result) {
  // Send result.token to your server for validation.
  console.log('pass_token:', result.token)
}

function handleError(error) {
  console.error('verification failed:', error)
}
</script>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `appKey` | `string` | *required* | CaptchaLa application key |
| `serverToken` | `string` | - | One-time, server-issued challenge token. Required when the app has `server_token_required=true`. |
| `product` | `'popup' \| 'float' \| 'embed' \| 'bind'` | `'popup'` | Display mode |
| `action` | `string` | `'default'` | Action identifier (e.g. `login`, `register`, `checkout`) |
| `lang` | `string` | `'zh-CN'` | Language code (`zh-CN`, `en`, `ja`, …) |
| `bindTo` | `string \| HTMLElement` | - | Element selector or node to bind to (only for `product="bind"`) |

## Events

| Event | Payload | Description |
|-------|---------|-------------|
| `success` | `{ token, type, action }` | Verification succeeded |
| `error` | `error` | Verification failed |
| `close` | — | CAPTCHA closed |
| `ready` | — | CAPTCHA ready |

## Methods (via `ref`)

```vue
<template>
  <Captchala ref="captchaRef" app-key="your-app-key" />
  <button @click="captchaRef?.verify()">Verify</button>
</template>

<script setup>
import { ref } from 'vue'
const captchaRef = ref()
</script>
```

| Method | Description |
|--------|-------------|
| `verify()` | Trigger verification |
| `reset()` | Reset CAPTCHA state |
| `destroy()` | Destroy the instance |
| `bindTo(selector)` | Bind to element (for `bind` mode) |
| `setLang(lang)` | Switch language in place |

## Production: `serverToken` mode

For high-value flows (login, register, payment) we recommend the **server-issued
token flow**. Your backend mints a one-time `server_token` (5-minute TTL) via
`POST /v1/server/challenge/issue` and hands it to the browser:

```vue
<template>
  <Captchala
    v-if="serverToken"
    :server-token="serverToken"
    app-key="pk_your_public_app_key"
    action="login"
    @success="onSuccess"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { Captchala } from '@captcha-la/vue'

const serverToken = ref()

onMounted(async () => {
  const r = await fetch('/api/captcha-token')   // your own backend
  serverToken.value = (await r.json()).server_token
})

function onSuccess(result) {
  console.log('pass_token:', result.token)
}
</script>
```

See [API Reference](/api-reference) for the full backend contract.

## Links

- [npm](https://www.npmjs.com/package/@captcha-la/vue) · [GitHub](https://github.com/Captcha-La/vue) · [example](https://github.com/Captcha-La/vue-example)
- [Web SDK overview](/web-sdk) · [API Reference](/api-reference)



<!-- Source: https://docs.captcha.la/sdk/ios -->

# iOS / macOS SDK

Apple-platform SDK for **iOS 15+** and **macOS 11+ (Big Sur)** via Mac Catalyst, shipped as an `.xcframework` plus a `.bundle` of localized assets. Drop-in for SwiftUI, UIKit, and AppKit projects.

## Demo on GitHub

::: tip 📦
[Captcha-La/iosmacos-demo](https://github.com/Captcha-La/iosmacos-demo) — full runnable example with every integration step.
:::

## Install

Add CaptchaLa to your `Podfile` (CocoaPods 1.10+):

```ruby
# Podfile
platform :ios, '13.0'

target 'YourApp' do
  use_frameworks!
  pod 'Captchala', '~> 1.0.2'
end
```

```bash
pod install
```

Or, if you prefer manual integration:

Download the latest iOS release from the [CaptchaLa dashboard](https://dash.captcha.la). The archive contains:

- `Captchala.xcframework` — the compiled SDK
- `Captchala.bundle` — localized resources

Drop both next to your `.xcodeproj`. The demo project references them by file name; no manual linking is needed beyond keeping their location stable.


For manual integration, download the xcframework directly: [dash.captcha.la/downloads](https://dash.captcha.la/downloads)

```text
YourApp/
├── YourApp.xcodeproj
├── YourApp/
├── Captchala.xcframework
└── Captchala.bundle
```

Open the project and run on the simulator, a device, or **My Mac (Mac Catalyst)**:

```bash
open YourApp.xcodeproj
# Cmd-R in Xcode
```

## Quick start

```swift
import SwiftUI
import Captchala

final class CaptchaDelegateBridge: NSObject, CaptchalaDelegate {
    var onSuccess: ((CaptchalaResult) -> Void)?
    var onFailure: ((CaptchalaError) -> Void)?
    var onClose:   (() -> Void)?

    func captcha(didSucceedWith result: CaptchalaResult) { onSuccess?(result) }
    func captcha(didFailWithError error: CaptchalaError) { onFailure?(error) }
    func captchaDidClose() { onClose?() }
}

struct LoginView: View {
    @State private var bridge = CaptchaDelegateBridge()
    @State private var status = "Tap to verify"

    var body: some View {
        Button("Verify with CAPTCHA", action: startVerify)
        Text(status).font(.caption)
    }

    private func startVerify() {
        bridge.onSuccess = { r in
            // Send r.passToken to your backend for validation.
            status = "OK: \(r.passToken)"
        }
        bridge.onFailure = { e in status = "ERROR [\(e.code)] \(e.message)" }

        Task { @MainActor in
            // 1. Fetch a one-shot server_token from YOUR backend.
            let token = await fetchServerTokenFromYourBackend()

            // 2. Build config and present.
            let config = CaptchalaConfigBuilder()
                .appKey("YOUR_APP_KEY")
                .action("login")
                .lang("en")              // en, zh-CN, zh-TW, ja, ko, ms, vi, id
                .theme("light")          // "light" | "dark"
                .enableVoice(true)
                .enableOfflineMode(true)
                .serverToken(token)
                .onServerTokenExpired { await fetchServerTokenFromYourBackend() }
                .build()

            guard let presenter = topViewController() else { return }
            CaptchalaClient.shared
                .initialize(config: config)
                .setDelegate(bridge)
                .verify(from: presenter)
        }
    }
}
```

::: tip Mac Catalyst & native macOS
The exact same Swift code runs on iOS, Mac Catalyst, and native macOS. On Catalyst pass any `UIViewController`. On native macOS use `NSViewController` and call `.verify()` without an argument — the SDK presents in its own `NSWindow`.
:::

## API surface

| Symbol | Purpose |
| --- | --- |
| `CaptchalaClient.shared` | Shared singleton. All entry points hang off this. |
| `CaptchalaConfigBuilder()` | Fluent builder. Set `appKey`, `action`, `lang`, `theme`, `enableVoice`, `enableOfflineMode`, `serverToken`. |
| `initialize(config:)` | Apply the built config. Returns `self` so you can chain `setDelegate`. |
| `setDelegate(_:)` | Provide an `NSObject` conforming to `CaptchalaDelegate`. The SDK keeps a weak reference. |
| `verify(from: presenter)` | Present the CAPTCHA over the given UIViewController (iOS / Catalyst). The SDK pushes a modal sheet. |
| `CaptchalaResult` | Returned via `captcha(didSucceedWith:)`. Fields: `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. |
| `onServerTokenExpired { … }` | Async closure that re-fetches a fresh `server_token` if the prior one expires mid-challenge. |

## Server-side validation

Forward `result.passToken` (or `result.token`) to your backend and validate it against the CaptchaLa API. Never expose `X-App-Secret` in client code.

```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": "<result.passToken>", "client_ip": "<end-user IP>" }
```

See the [API Reference](../api-reference) for the full validation endpoint and `X-App-Key` / `X-App-Secret` flow.

## Troubleshooting

- **`Captchala.xcframework` not found**  
  The `.xcframework` and `.bundle` must sit next to `Example.xcodeproj`. The demo references both by file name; keep their location stable when updating the SDK.

- **Mac Catalyst destination missing**  
  In Xcode, enable *Mac (Mac Catalyst)* under your target's *Supported Destinations*. The demo target ships with `SUPPORTS_MACCATALYST = YES`.

- **Modal not appearing**  
  Pass a real `UIViewController` to `verify(from:)`. The demo walks `UIApplication.connectedScenes` to find the topmost active key-window controller — copy that helper if you only have a SwiftUI `View`.

- **`Info.plist` privacy strings on macOS**  
  For Catalyst / native macOS targets enable the **Outgoing Connections (Client)** sandbox capability. The SDK only makes HTTPS calls, no microphone or camera access.

## Requirements

- iOS 15+ (device or simulator)
- macOS 11+ (Big Sur) via Mac Catalyst, macOS 13+ for native targets
- Xcode 15+
- Swift 5.7+ (async/await)



<!-- Source: https://docs.captcha.la/sdk/android -->

# Android SDK

Android SDK for **Android 5.0+ (API 21+)**, packaged as a single `.aar`. Compose- and View-based apps both work; the SDK is UI-framework-agnostic.

## Demo on GitHub

::: tip 📦
[Captcha-La/android-demo](https://github.com/Captcha-La/android-demo) — full runnable example with every integration step.
:::

## Install

The SDK ships as a single `.aar` you download from the [CaptchaLa dashboard](https://dash.captcha.la). Drop it into your app module's `libs/` folder and reference it from Gradle:

```groovy
// settings.gradle (or repositories block)
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

// app/build.gradle
android {
    defaultConfig {
        minSdk 21
    }
}

dependencies {
    implementation 'la.captcha:captchala:1.0.2'   // Maven Central
}
```

Or download the AAR for manual integration:

```groovy
// app/build.gradle (drop captchala.aar into app/libs/)
android {
    defaultConfig {
        minSdk 21
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
}

dependencies {
    implementation files('libs/captchala.aar')
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.code.gson:gson:2.10.1'
    implementation 'org.bouncycastle:bcprov-jdk18on:1.77'
}
```

Download: [dash.captcha.la/downloads](https://dash.captcha.la/downloads) (latest AAR).

```xml
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

Build and install the demo with:

```bash
./gradlew installDebug
```

## Quick start

```kotlin
import la.captcha.sdk.CaptchalaClient
import la.captcha.sdk.CaptchalaConfig
import la.captcha.sdk.CaptchalaError
import la.captcha.sdk.CaptchalaListener
import la.captcha.sdk.CaptchalaResult

class LoginActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 1. Fetch a one-shot server_token from YOUR backend
        //    (which calls the CaptchaLa server API with X-App-Key + X-App-Secret).
        val serverToken = runBlocking { fetchServerTokenFromYourBackend() }

        // 2. Build config — destroy any prior client so a fresh state is built.
        CaptchalaClient.destroy()
        val client = CaptchalaClient.getClient(applicationContext).init(
            CaptchalaConfig.Builder()
                .appKey("YOUR_APP_KEY")
                .action("login")            // login, register, pay, …
                .lang("en")                 // en, zh-CN, zh-TW, ja, ko, ms, vi, id
                .theme("light")             // "light" | "dark"
                .enableVoice(true)
                .enableOfflineMode(true)
                .serverToken(serverToken)
                .onServerTokenExpired { fetchServerTokenFromYourBackend() }
                .build()
        )

        // 3. Listen for terminal events.
        client.setListener(object : CaptchalaListener {
            override fun onReady() { /* challenge UI ready */ }
            override fun onSuccess(result: CaptchalaResult) {
                // Send result.passToken to your backend for validation.
                sendToBackend(result.passToken)
            }
            override fun onFail(error: CaptchalaError)  { /* recoverable */ }
            override fun onError(error: CaptchalaError) { /* terminal */ }
            override fun onClose() { /* user dismissed */ }
        })

        // 4. Open the CAPTCHA from a button tap.
        findViewById<Button>(R.id.btnVerify).setOnClickListener {
            client.verify(this)
        }
    }
}
```

## API surface

| Symbol | Purpose |
| --- | --- |
| `CaptchalaClient.getClient(ctx)` | Singleton entry point. Returns the shared client bound to the app context. |
| `CaptchalaConfig.Builder()` | Fluent builder for `appKey`, `action`, `lang`, `theme`, `enableVoice`, `enableOfflineMode`, `serverToken`. |
| `init(config)` | Initialize the client with a built `CaptchalaConfig`. Cheap to call — destroys and re-builds state if invoked again. |
| `setListener(listener)` | Register a `CaptchalaListener` for `onReady`, `onSuccess`, `onFail`, `onError`, `onClose` callbacks. |
| `verify(activity)` | Open the CAPTCHA on top of the given Activity. Result is delivered through the listener. |
| `CaptchalaResult` | Holds `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Send `passToken` to your backend. |
| `CaptchalaClient.destroy()` | Tear down the singleton (release WebView, native handles). Call from `Activity.onDestroy` if you re-init often. |

## Server-side validation

Forward `result.passToken` (or `result.token`) to your backend and validate it against the CaptchaLa API. Never expose `X-App-Secret` in client code.

```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": "<result.passToken>", "client_ip": "<end-user IP>" }
```

See the [API Reference](../api-reference) for the full validation endpoint and `X-App-Key` / `X-App-Secret` flow.

## Troubleshooting

- **`UnsatisfiedLinkError` at startup**  
  Make sure your `abiFilters` covers `armeabi-v7a`, `arm64-v8a`, `x86`, `x86_64` so all device shapes find a matching native lib. The demo's `app/build.gradle` shows the exact filter list.

- **ProGuard / R8 strips SDK classes in release**  
  Add a keep rule for the SDK package, e.g. `-keep class la.captcha.sdk.** { *; }` and `-dontwarn la.captcha.sdk.**` in your `proguard-rules.pro`.

- **`minSdkVersion` too low**  
  The SDK requires `minSdkVersion 21` (Android 5.0). Lower targets will fail at compile time.

- **Cleartext HTTP traffic blocked**  
  Your manifest should have `android:usesCleartextTraffic="false"` (the demo does). The CaptchaLa endpoint is HTTPS-only.

## Requirements

- Android 5.0+ (`minSdkVersion 21`)
- AndroidX (`compileSdk` 33+)
- Kotlin 1.8+ or equivalent Java toolchain (Java 17 source / target)
- ABIs: `armeabi-v7a`, `arm64-v8a`, `x86`, `x86_64`



<!-- Source: https://docs.captcha.la/sdk/flutter -->

# Flutter SDK

Flutter plugin built on the native iOS / Android SDKs, exposing a single Dart `CaptchalaClient` for both mobile platforms (with Linux / macOS / Windows desktop support via embedded WebView).

## Demo on GitHub

::: tip 📦
[Captcha-La/flutter-demo](https://github.com/Captcha-La/flutter-demo) — full runnable example with every integration step.
:::

## Install

Add the package from pub.dev:

```yaml
# pubspec.yaml
dependencies:
  captchala: ^1.3.2
  http: ^1.2.0          # used by the demo's token-fetch helpers
```

```bash
flutter pub get
flutter run               # auto-picks the foreground device
# or:
flutter run -d <device-id>
```

For iOS / macOS the first build runs `pod install` automatically. Make sure `ios/Podfile` declares `platform :ios, '13.0'` (or higher).

## Quick start

```dart
import 'package:flutter/material.dart';
import 'package:captchala/captchala.dart';

class LoginScreen extends StatefulWidget {
  const LoginScreen({super.key});
  @override
  State<LoginScreen> createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  String _status = 'Tap to verify';
  bool _verifying = false;

  Future<void> _runVerify() async {
    setState(() { _verifying = true; _status = 'Fetching server_token...'; });

    // 1. Fetch a one-shot server_token from YOUR backend.
    final initialToken = await fetchServerTokenFromYourBackend();

    // 2. Build config from your business action.
    final config = CaptchalaConfig(
      appKey: 'YOUR_APP_KEY',
      action: 'login',                  // login, register, pay, …
      lang: 'en',                       // en, zh-CN, zh-TW, ja, ko, ms, vi, id
      theme: 'light',                   // 'light' | 'dark'
      enableVoice: true,
      enableOfflineMode: true,
      maskClosable: false,
      serverToken: initialToken,
    );

    // 3. Initialize, register callbacks, then call verify().
    final client = await CaptchalaClient.instance.initialize(config);
    client.setCallbacks(
      onSuccess: (r) async {
        // Send r.passToken to YOUR backend for validation.
        if (!mounted) return;
        setState(() { _status = 'OK: ${r.passToken}'; _verifying = false; });
      },
      onFail:    (e) { if (mounted) setState(() { _status = 'fail: ${e.code}'; _verifying = false; }); },
      onError:   (e) { if (mounted) setState(() { _status = 'error: ${e.code} ${e.message}'; _verifying = false; }); },
      onClose:   () { if (mounted && _verifying) setState(() { _status = 'closed'; _verifying = false; }); },
      onServerTokenExpired: () => fetchServerTokenFromYourBackend(),
    );
    await client.verify();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(mainAxisSize: MainAxisSize.min, children: [
          ElevatedButton(
            onPressed: _verifying ? null : _runVerify,
            child: Text(_verifying ? 'Verifying...' : 'Verify with CAPTCHA'),
          ),
          const SizedBox(height: 12),
          Text(_status, style: const TextStyle(fontFamily: 'monospace')),
        ]),
      ),
    );
  }
}
```

## API surface

| Symbol | Purpose |
| --- | --- |
| `CaptchalaClient.instance` | Singleton accessor for the plugin. |
| `CaptchalaConfig(...)` | Plain Dart record: `appKey`, `action`, `lang`, `theme`, `enableVoice`, `enableOfflineMode`, `maskClosable`, `serverToken`. |
| `await client.initialize(config)` | Apply config. Returns the same client instance so you can chain `setCallbacks`. |
| `setCallbacks(...)` | Register `onSuccess`, `onFail`, `onError`, `onClose`, `onServerTokenExpired` callbacks. |
| `await client.verify()` | Open the native CAPTCHA view (Android: Activity over Flutter; iOS: UIViewController over Flutter). |
| `CaptchalaResult` | Provided to `onSuccess`. Fields: `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. |

## Server-side validation

Forward `result.passToken` (or `result.token`) to your backend and validate it against the CaptchaLa API. Never expose `X-App-Secret` in client code.

```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": "<result.passToken>", "client_ip": "<end-user IP>" }
```

See the [API Reference](../api-reference) for the full validation endpoint and `X-App-Key` / `X-App-Secret` flow.

## Troubleshooting

- **iOS pod install fails**  
  In `ios/Podfile` set `platform :ios, '13.0'` (or higher). Run `flutter clean && flutter pub get && cd ios && pod install` after switching the plugin version.

- **Android `minSdkVersion` mismatch**  
  Bump `android/app/build.gradle` to `minSdkVersion 21`. The native Android SDK will refuse to compile below that.

- **Callbacks fire on background isolate**  
  Always guard `setState` with `if (mounted)` before mutating UI state inside callbacks. The demo wraps every callback that updates state with this check.

- **Desktop targets (Linux / Windows / macOS)**  
  Linux requires GTK3 + WebKitGTK + libcurl. Windows needs the Edge WebView2 Runtime (Win 10 1809+). macOS desktop uses the system WebView automatically.

## Requirements

- Flutter 3.10+ / Dart 3.0+
- Android: `minSdkVersion 21` (Android 5.0+)
- iOS: 13.0+ with CocoaPods
- Desktop (optional): GTK3 + WebKitGTK on Linux, WebView2 Runtime on Windows 10 1809+



<!-- Source: https://docs.captcha.la/sdk/electron -->

# Electron SDK

Electron SDK runs entirely in the **main process**, opening a native, OS-managed CAPTCHA window. The renderer never touches the verification — keep it that way for security.

## Demo on GitHub

::: tip 📦
[Captcha-La/electron-demo](https://github.com/Captcha-La/electron-demo) — full runnable example with every integration step.
:::

## Install

```bash
npm install @captchala/electron
```

The package targets **Electron 28+** (the demo pins `^33.0.0`) and **Node 18+**. Run the demo end-to-end with:

```bash
npm install
npm start
```

## Quick start

```js
// main.js (Electron main process — never the renderer)
const { app, BrowserWindow, ipcMain } = require('electron');
const path = require('path');
const { CaptchalaClient } = require('@captchala/electron');

let currentClient = null;

ipcMain.handle('verify', async (event, opts) => {
  // 1. Fetch a one-shot server_token from YOUR backend.
  const serverToken = await fetchServerTokenFromYourBackend(opts.action);

  // 2. Tear down any prior client, then build a fresh one.
  if (currentClient) { currentClient.destroy(); currentClient = null; }
  currentClient = new CaptchalaClient({
    appKey: 'YOUR_APP_KEY',
    serverToken,
    action: opts.action,        // 'login' | 'register' | 'pay' | …
    lang:   opts.lang,          // 'en' | 'zh-CN' | 'ja' | …
    theme:  opts.theme,         // 'light' | 'dark'
    timeoutMs: 15000,
    retryCount: 3,
    onReady: () => event.sender.send('captcha-status', 'ready'),
    onFail:  (e) => event.sender.send('captcha-status', `recoverable: ${e.code}`),
  });

  try {
    const result = await currentClient.verify();
    // Send result.passToken to YOUR backend for validation.
    return { success: true, passToken: result.passToken };
  } catch (err) {
    return { success: false, error: err.message };
  } finally {
    if (currentClient) { currentClient.destroy(); currentClient = null; }
  }
});

function createWindow() {
  const win = new BrowserWindow({
    width: 520, height: 640, resizable: false,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
    },
  });
  win.loadFile('index.html');
}

app.whenReady().then(createWindow);
app.on('window-all-closed', () => app.quit());
```

```js
// preload.js — bridge the renderer to the main-process verify().
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('captchala', {
  verify:   (opts)     => ipcRenderer.invoke('verify', opts),
  onStatus: (callback) => ipcRenderer.on('captcha-status', (_, msg) => callback(msg)),
});
```

## API surface

| Symbol | Purpose |
| --- | --- |
| `new CaptchalaClient({...})` | Construct a one-shot client. Pass `appKey`, `serverToken`, `action`, `lang`, `theme`, `timeoutMs`, `retryCount`, plus event handlers. |
| `await client.verify()` | Open the native CAPTCHA window. Resolves with a result on success, rejects on hard error. |
| `onReady` / `onFail` | Optional handlers passed in the constructor. `onFail` is for *recoverable* failures (the SDK will retry). |
| `result.passToken` | The token to validate on your backend. Always opaque to the client. |
| `client.destroy()` | Close the window and release resources. Always call once you are done with a client instance. |
| `CaptchalaClient.version()` | Static helper that returns the SDK version string. Useful in support / debug overlays. |

## Server-side validation

Forward `result.passToken` (or `result.token`) to your backend and validate it against the CaptchaLa API. Never expose `X-App-Secret` in client code.

```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": "<result.passToken>", "client_ip": "<end-user IP>" }
```

See the [API Reference](../api-reference) for the full validation endpoint and `X-App-Key` / `X-App-Secret` flow.

## Troubleshooting

- **Don't import the SDK in the renderer**  
  `@captchala/electron` is **main-process only**. Expose its result through `contextBridge` + `ipcRenderer.invoke()` like the demo's `preload.js` does. Keep `nodeIntegration: false` and `contextIsolation: true`.

- **Module not found at runtime**  
  `@captchala/electron` is a regular dependency, not a devDependency — it must be packaged into your final app. Bundlers like electron-builder include it automatically.

- **Window opens behind your main window**  
  This is a Linux/X11 quirk. Pass `parent` in your own `BrowserWindow` if you wrap the CAPTCHA window, or call `mainWindow.focus()` after `verify()` returns.

- **`Electron 28+` required**  
  The demo declares `electron: ^33.0.0`. Older Electron may miss APIs the SDK relies on; pin to `28+` and Node 18+.

## Requirements

- Electron 28+ (the demo uses 33.x)
- Node 18+
- Cross-platform: macOS, Windows 10 1809+, Linux (X11 / Wayland)



<!-- Source: https://docs.captcha.la/sdk/server-php -->

# PHP Server SDK

Official PHP server-side SDK — published as [`captchala/captchala-php`](https://packagist.org/packages/captchala/captchala-php) on Packagist.

Three jobs the SDK handles for you:

1. **Validate** — verify a `pt_` pass token from the browser SDK.
2. **Issue** — mint a one-time `sct_` server token to bind the upcoming challenge to a specific action / IP / UID.
3. **Moderate** — multi-modal (text + image) content moderation against the same OpenAI-compatible pipeline the dashboard uses.

## Install

```bash
composer require captchala/captchala-php
```

Requires **PHP ≥ 8.0** with `ext-json`. Uses cURL when available, falls back to `file_get_contents`.

## Validate (`pt_` token)

```php
use Captchala\Client;

$client = new Client('your_app_key', 'your_app_secret');
$result = $client->validate($_POST['captcha_token']);

if (!$result->isValid()) {
    http_response_code(400);
    exit($result->getError());   // e.g. "token_expired", "client_ip_mismatch"
}
// Verification passed; proceed with the request.
```

If you issued the original `server_token` with `bind_uid`, compare the `uid` returned with the user you actually expect:

```php
if ($result->getUid() !== $expectedUserId) {
    http_response_code(400);
    exit('user mismatch');
}
```

If you bound the token to an IP, pass the user IP on the verify side too:

```php
$client->validate($token, false, $request->ip());
```

## Issue a server token

For high-value flows (login, register, payment) the recommended pattern is:
backend mints a one-time `sct_` token, hands it to the browser, browser passes
it as the `serverToken` prop. Each token is single-use, action-scoped, and
optionally bound to IP / UID at issuance time.

```php
$issue = $client->issueServerToken(
    action:    'login',
    bindingIp: $request->ip(),
    ttl:       300,         // seconds; default 300
    maxUses:   5,           // SDK retry budget
    bindUid:   $user->id,   // pair with ValidateResult::getUid() on verify
);

if (!$issue->isOk()) {
    return ['error' => $issue->getError()];   // rate_limit_exceeded, invalid_action, ...
}

return ['server_token' => $issue->getToken()];  // hand to browser
```

## Moderate content

Multi-modal — accepts a mix of text and image URLs in OpenAI-compatible format:

```php
$result = $client->moderationCheck([
    ['type' => 'text', 'text' => $userComment],
    ['type' => 'image_url', 'image_url' => ['url' => $uploadedImageUrl]],
], userId: $user->id);

if (!$result->isOk()) {
    // request error: invalid_credentials, no_content, transport failure, ...
    return ['error' => $result->getError()];
}

if ($result->isFlagged()) {
    // upstream model flagged; inspect categories for the why
    if ($result->hasCategory('violence', 'csam')) {
        // hard block
    }
}
```

Plain-text shortcut:

```php
$result = $client->moderationText('user comment here', userId: $user->id);
```

Categories are model-defined (e.g. `violence`, `hate`, `sexual`, `self-harm`); iterate `getCategories()` defensively rather than hard-coding a fixed set.

## Result classes

| Class | Methods |
|---|---|
| `ValidateResult` | `isValid()`, `getError()`, `getUid()`, `getChallengeId()`, `getAction()`, `isOffline()`, `isClientOnly()`, `getWarning()`, `toArray()` |
| `IssueResult` | `isOk()`, `getToken()`, `getExpiresIn()`, `getIssuedAt()`, `getError()`, `getMessage()`, `toArray()` |
| `ModerationResult` | `isOk()`, `isFlagged()`, `hasCategory(...$names)`, `getCategories()`, `getContentType()`, `getRaw()`, `getError()`, `getMessage()`, `toArray()` |

## Links

- [Packagist](https://packagist.org/packages/captchala/captchala-php) · [GitHub](https://github.com/Captcha-La/captchala-php)
- [Web SDK overview](/web-sdk) · [API Reference](/api-reference)



<!-- Source: https://docs.captcha.la/sdk/server-go -->

# Go Server SDK

Official Go server-side SDK — `github.com/Captcha-La/captchala-go`.

Three jobs the SDK handles for you:

1. **Validate** — verify a `pt_` pass token from the browser SDK.
2. **Issue** — mint a one-time `sct_` server token to bind the upcoming challenge to a specific action / IP / UID.
3. **Moderate** — multi-modal (text + image) content moderation against the same OpenAI-compatible pipeline the dashboard uses.

## Install

```bash
go get github.com/Captcha-La/captchala-go
```

Stdlib only. No external dependencies.

## Validate (`pt_` token)

```go
import captchala "github.com/Captcha-La/captchala-go"

client := captchala.NewClient(appKey, appSecret)

result, err := client.Validate(passToken)
if err != nil || !result.Valid {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}
// proceed with the request
```

If the original `server_token` was issued with `bind_uid`, compare:

```go
if result.UID != expectedUserID {
    http.Error(w, "user mismatch", http.StatusBadRequest)
    return
}
```

For IP-bound tokens, pass the user IP on the verify side:

```go
result, err := client.ValidateWithClientIP(passToken, false, userIP)
```

## Issue a server token

Recommended for high-value flows (login, register, payment): backend mints a
one-time `sct_` token, hands it to the browser, browser uses it as the
`serverToken` prop. Single-use, action-scoped, optionally IP/UID-bound.

```go
issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // backend rejects token if a different IP redeems it
    TTL:       300,       // seconds
    MaxUses:   5,         // SDK retry budget
    BindUID:   userID,    // pair with ValidateResult.UID on verify
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// hand issue.Token to the browser
```

Defaults-only shortcut:

```go
issue, err := client.IssueServerToken("login")
```

## Moderate content

Multi-modal — accepts a slice of `ModerationItem` (text and/or image_url in
OpenAI-compatible format):

```go
result, err := client.ModerationCheck([]captchala.ModerationItem{
    captchala.TextItem(userComment),
    captchala.ImageURLItem(uploadedImageURL),
}, userID)

if err != nil || !result.OK {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}

if result.Flagged {
    if result.HasCategory("violence", "csam") {
        // hard block
    }
}
```

Plain-text shortcut:

```go
result, err := client.ModerationText("user comment here", userID)
```

Categories are model-defined; iterate `result.Categories` defensively rather
than hard-coding a fixed set.

## Types

| Type | Fields |
|---|---|
| `ValidateResult` | `Valid`, `Error`, `UID`, `ChallengeID`, `Action`, `Offline`, `ClientOnly`, `Warning` |
| `IssueResult` | `OK`, `Token`, `ExpiresIn`, `IssuedAt`, `Error`, `Message` |
| `IssueOptions` | `BindingIP`, `TTL`, `MaxUses`, `BindUID` |
| `ModerationItem` | `Type`, `Text`, `ImageURL` (use `TextItem()` / `ImageURLItem()` helpers) |
| `ModerationResult` | `OK`, `Flagged`, `Categories`, `ContentType`, `Raw`, `Error`, `Message`; method `HasCategory(...names)` |

## Links

- [pkg.go.dev](https://pkg.go.dev/github.com/Captcha-La/captchala-go) · [GitHub](https://github.com/Captcha-La/captchala-go)
- [Web SDK overview](/web-sdk) · [API Reference](/api-reference)



<!-- Source: https://docs.captcha.la/integrations/wordpress -->

# WordPress

Official CaptchaLa plugin for WordPress. Adds CAPTCHA verification to core WordPress forms and to the most common form, e-commerce and community plugins without writing any code.

## What it covers

Each item below is an individual checkbox in the plugin's settings panel — you only enable the surfaces you actually want to protect.

- WordPress login
- WordPress registration
- WordPress comments
- WordPress lost-password
- WooCommerce checkout
- WooCommerce account creation
- WooCommerce login
- Contact Form 7
- Gravity Forms
- WPForms
- Elementor Forms
- BBPress (topics and replies)
- BuddyPress (registration and activity)

If a form plugin is not installed, its toggle is hidden — the plugin detects available integrations at boot.

## Install

### 1. Install the plugin

Two options:

- **WordPress admin** — `Plugins` → `Add New`, search `CaptchaLa`, click **Install** then **Activate**.
- **Manual upload** — download the latest release zip from
  [`github.com/Captcha-La/captchala-wordpress/releases`](https://github.com/Captcha-La/captchala-wordpress/releases),
  upload via `Plugins` → `Add New` → `Upload Plugin`, and activate.

The plugin targets WordPress ≥ 6.0 and PHP ≥ 7.4.

### 2. Get your keys

Sign up at [`dash.captcha.la`](https://dash.captcha.la), create an application, then copy:

- **App Key** — public, embedded in the page
- **App Secret** — server-side only, used by WordPress to call `/v1/validate`

### 3. Wire it up

In WP-Admin, open `CaptchaLa` in the left menu:

1. Paste the **App Key** and **App Secret**.
2. Pick a verification mode (popup, bind, embed or float — see [Web SDK](/web-sdk)).
3. Toggle the forms you want protected.
4. Click **Save changes**.

Open one of the protected forms in a private window to confirm the challenge renders.

## Configuration

All settings live under `WP-Admin → CaptchaLa`. The plugin stores them as a single WordPress option (`captchala_settings`).

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| App Key | string | — | Public key (`cl_pub_…`) from the CaptchaLa dashboard. Required. |
| App Secret | string | — | Server secret. Required. Never exposed to the browser. |
| Verification mode | enum | `popup` | One of `popup`, `bind`, `embed`, `float`. Maps to the Web SDK `product` option. |
| Form toggles | bool[] | all off | One toggle per supported form (see [What it covers](#what-it-covers)). |
| Lazy load | bool | `true` | When on, the CaptchaLa loader is only enqueued on pages that contain a protected form. |
| Theme | enum | `auto` | `light`, `dark`, or `auto` (follows the user's system preference). |
| Action label | string | per-form | The `action` string sent on validation (`login`, `register`, `comment`, `wc_checkout`, etc). The plugin sets sensible defaults — override only if you have a reason. |
| Bind to IP | bool | `true` | Sends the visitor IP at issuance and validation. Disable behind a proxy that does not forward client IPs. |
| Block on verification failure | bool | `true` | When off, failed verifications are logged but the form still submits. Use for staged rollout, not production. |

Settings can also be exported / imported as JSON from the settings page footer.

## FAQ

**Is the plugin free?**

Yes. The WordPress plugin is free. The CaptchaLa free plan covers 1,000 verifications a month — paid plans only apply if you need more volume.

**Will it slow down my site?**

The loader is enqueued lazily, only on pages that render a protected form. The verification call returns from the edge in under 100ms in most regions. There is no front-page tracking script.

**Does it work with WooCommerce?**

Yes. Checkout, account creation and login are supported out of the box — each is a separate toggle. The plugin hooks WooCommerce's standard validation pipeline, so failed verifications surface as normal WooCommerce form errors.

**Do I need to write code?**

No. Install, paste two keys, toggle the forms you want to protect. There are filters available if you need to customize behaviour, but they are optional.

**Is it GDPR-compliant?**

CaptchaLa is privacy-first: no third-party tracking pixels, no advertising signals, and the WordPress plugin transmits only what is needed to verify a single challenge. Per-request export and deletion are available through the CaptchaLa dashboard.

## Source

- Plugin repository: [`github.com/Captcha-La/captchala-wordpress`](https://github.com/Captcha-La/captchala-wordpress)
- Issues / feature requests: filed against the repository above
- Related: [Web SDK](/web-sdk) · [PHP Server SDK](/sdk/server-php) · [API Reference](/api-reference)



<!-- Source: https://docs.captcha.la/integrations/flarum -->

# Flarum

Official CaptchaLa extension for Flarum. Adds CAPTCHA verification to the actions bots typically target on a forum — registration, login, password reset and posting — with per-action toggles in the admin panel.

## What it covers

Each action below is an individual toggle under `Admin → Extensions → CaptchaLa`.

- Registration
- Login
- Password reset
- Post replies
- New discussions
- Profile edits

Authenticated sessions opened via an SSO / Auth Sync provider are exempt — see [SSO / Auth Sync](#sso-auth-sync) below.

## Install

### 1. Require the extension

From your Flarum installation root:

```bash
composer require captchala/flarum
```

Alternatively, in `Admin → Extension Manager` paste `captchala/flarum` into the **Install** field. The extension targets Flarum ≥ 1.8 and PHP ≥ 8.1.

### 2. Enable in admin panel

Open `Admin → Extensions`, find **CaptchaLa**, and click **Enable**.

### 3. Configure

In the extension's settings panel:

1. Paste your **App Key** and **App Secret** from [`dash.captcha.la`](https://dash.captcha.la).
2. Toggle which actions to protect.
3. Save.

## Configuration

Settings are stored in the standard Flarum settings table under the `captchala.*` prefix.

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| App Key | string | — | Public key (`cl_pub_…`) from the CaptchaLa dashboard. Required. |
| App Secret | string | — | Server secret. Required. Used server-side only to call `/v1/validate`. |
| Protect registration | bool | `true` | Challenge on sign-up. |
| Protect login | bool | `false` | Challenge on the login modal. Off by default because most forums protect login via rate limiting. |
| Protect password reset | bool | `true` | Challenge when requesting a password-reset email. |
| Protect post replies | bool | `false` | Challenge when posting a reply. Off by default; enable if the forum is under spam pressure. |
| Protect new discussions | bool | `false` | Challenge when opening a discussion. |
| Verification mode | enum | `popup` | One of `popup`, `bind`, `embed`. Maps to the Web SDK `product` option. |
| Theme | enum | `auto` | `light`, `dark`, or `auto`. |
| Skip for trusted users | bool | `true` | Users in groups marked as trusted (e.g. moderators) bypass the challenge. |

## SSO / Auth Sync

The extension cooperates with Flarum's standard auth-provider hooks (`UserAuthenticated`, third-party Auth Sync providers, OAuth bridges).

- If the user arrives via an authenticated SSO session, no challenge is rendered — the extension treats the session as already verified.
- For mixed setups where some users sign in via SSO and others via the local form, only the local form path runs the challenge.
- The `skip_for_trusted_users` toggle stacks on top of this: trusted groups bypass the challenge even on a local-form login.

## FAQ

**Is the extension free?**

Yes. The Composer package is free. The CaptchaLa free plan covers 1,000 verifications a month.

**Does it stop spam sign-ups?**

It blocks or challenges most automated registrations at the first risk score. No CAPTCHA blocks 100% — but in our test forums, spam registration volume drops by roughly an order of magnitude after enabling.

**Can I require it only on registration?**

Yes. Each action is a separate toggle. The default profile enables registration and password reset only.

**Does it work with SSO / Auth Sync?**

Yes. Sessions opened by an SSO / Auth Sync provider skip the challenge. See [SSO / Auth Sync](#sso-auth-sync).

**Is it open source?**

Yes — the PHP extension code is open source. Verification calls are made against the hosted CaptchaLa service.

## Source

- Extension repository: [`github.com/Captcha-La/captchala-flarum`](https://github.com/Captcha-La/captchala-flarum)
- Packagist: [`captchala/flarum`](https://packagist.org/packages/captchala/flarum)
- Related: [Web SDK](/web-sdk) · [PHP Server SDK](/sdk/server-php) · [API Reference](/api-reference)