---
title: Referensi API
---

# Referensi API

CaptchaLa menyediakan RESTful API untuk semua integrasi sisi server.

## Base URL

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

## Autentikasi

Semua request API membutuhkan header autentikasi:

```
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.
:::

## API Validasi Sisi Server

> 💡 **Gunakan SDK server untuk lewati boilerplate.** Membungkus endpoint, retry, error bertipe:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php)
> - **Go** — `go get github.com/Captcha-La/captchala-go`

Setelah pengguna lulus CAPTCHA di frontend, server Anda perlu memvalidasi token yang dikembalikan SDK. Berikut endpoint validasi sisi server.

### Validasi Token Sisi Server

Validasi pass_token yang dikembalikan SDK frontend (prefix pt_). Membutuhkan header X-App-Key dan 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` bersifat opsional tetapi disarankan — IP pengguna akhir dari request masuk Anda, dipakai untuk pemeriksaan risiko tambahan; aman untuk dihilangkan.

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

`captcha_args` adalah data informasional (untuk logging / analisis risiko Anda): `platform`, `user_ip` (IP saat tantangan diselesaikan), `referer`, `pkg`, `solved_at`, `risk_score`.

::: 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.
:::

## Challenge Token yang Diterbitkan Server {#server-token}

Terbitkan server_token berumur pendek dari backend Anda. Browser lalu meneruskan token ini saat menginisialisasi challenge, membuktikan bahwa request berasal dari server tepercaya Anda.

### Terbitkan Server Token

Panggil endpoint ini hanya dari server Anda sendiri. Membutuhkan X-App-Key + X-App-Secret. Respons berisi server_token (prefix sct_) yang akan diteruskan frontend ke inisialisasi verifikasi.

```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 | Deskripsi |
| --- | --- |
| `action` | Scene bisnis, mis. login, register, pay. Harus cocok dengan action yang digunakan di inisialisasi verifikasi. |
| `ttl` | Masa berlaku token dalam detik. Default 300, maksimum 900. |
| `max_uses` | Maksimal jumlah token dapat dikonsumsi. Default 10. |
| `bind_ip` | Ikat token ke IP client. Inisialisasi dari IP lain akan ditolak. |
| `bind_device_id` | Ikat token ke device id tertentu. |
| `bind_fingerprint` | Ikat token ke fingerprint browser tertentu. |

### Inisialisasi Challenge

Dipanggil oleh SDK untuk memulai CAPTCHA challenge. Menerima server_token opsional yang diterbitkan oleh /v1/server/challenge/issue.

| Field | Deskripsi |
| --- | --- |
| `app_key` | App Key publik Anda. |
| `action` | Scene bisnis. Harus cocok dengan action yang digunakan saat menerbitkan server_token. |
| `server_token` | Opsional; wajib ketika app memiliki server_token_required = true. |

::: info
Jika server_token_required diaktifkan untuk app ini di dashboard, inisialisasi verifikasi akan menolak request yang tidak membawa server_token yang valid.
:::

## Error Code

| Kode | Deskripsi |
| --- | --- |
| `invalid_app_key` | App Key tidak valid |
| `invalid_app_secret` | App Secret tidak valid |
| `challenge_expired` | Challenge kedaluwarsa |
| `challenge_not_found` | Challenge tidak ditemukan |
| `invalid_answer` | Jawaban tidak valid |
| `token_expired` | Token kedaluwarsa |
| `token_already_used` | Token sudah digunakan |
| `token_not_found` | Token tidak ditemukan |
| `quota_exceeded` | Kuota terlampaui |
| `rate_limited` | Terkena rate limit |
| `rate_limit_exceeded` | Terlalu banyak request penerbitan untuk app ini. Lakukan back off dan coba lagi. |