---
title: 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 (core SDK)

The core SDK is **CDN-only** — load it from the loader script. It is not
published to npm on purpose: the anti-bot logic must be updatable in real time,
and a pinned npm version would become a permanent vulnerability window.

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

### Framework wrappers (npm)

Vue / React projects can install a thin wrapper from npm — it still loads the
core SDK from the CDN at runtime.

```bash
npm install @captcha-la/vue     # see the Vue SDK page
npm install @captcha-la/react   # see the React SDK page
```

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

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