---
title: API 레퍼런스
---

# API 레퍼런스

CaptchaLa는 모든 서버 측 통합을 위한 RESTful API 를 제공합니다.

## Base URL

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

## 인증

모든 API 요청에는 인증 헤더가 필요합니다:

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

> 💡 **서버 SDK로 보일러플레이트 생략.** 엔드포인트·재시도·타입 에러를 래핑:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php)
> - **Go** — `go get github.com/Captcha-La/captchala-go`

사용자가 프런트엔드 CAPTCHA 를 통과한 뒤, 서버는 SDK 가 반환한 token 을 검증해야 합니다. 아래는 서버 측 검증 엔드포인트입니다.

### 서버 측 Token 검증

프런트엔드 SDK 가 반환한 pass_token(pt_ 접두사)을 검증합니다. X-App-Key 와 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` 는 선택 사항이지만 권장됩니다 — 백엔드로 들어온 요청에서 얻은 최종 사용자 IP 로, 추가 위험 검사에 사용됩니다. 생략해도 안전합니다.

```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` 는 참고용 필드입니다(로깅이나 위험 분석용): `platform`, `user_ip`, `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 {#server-token}

백엔드에서 짧은 수명의 server_token 을 발급합니다. 브라우저는 challenge 초기화 시 이 token 을 전달하여 요청이 신뢰된 서버에서 왔음을 증명합니다.

### Server Token 발급

이 엔드포인트는 자체 서버에서만 호출해야 합니다. X-App-Key + X-App-Secret 이 필요합니다. 응답에는 프런트엔드가 인증 초기화 으로 전달하는 server_token(sct_ 접두사)이 포함됩니다.

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

#### 본문 파라미터 (form-urlencoded)

| 필드 | 설명 |
| --- | --- |
| `action` | 비즈니스 장면, 예: login, register, pay. 인증 초기화 에서 사용하는 action 과 일치해야 합니다. |
| `ttl` | token 수명(초). 기본 300, 최대 900. |
| `max_uses` | token 최대 사용 횟수. 기본 10. |
| `bind_ip` | token 을 클라이언트 IP 에 바인딩합니다. 다른 IP 에서 초기화하면 거부됩니다. |
| `bind_device_id` | token 을 특정 디바이스 id 에 바인딩합니다. |
| `bind_fingerprint` | token 을 특정 브라우저 지문에 바인딩합니다. |

### Challenge 초기화

SDK 가 CAPTCHA challenge 를 시작할 때 호출합니다. /v1/server/challenge/issue 에서 발급된 선택적 server_token 을 받을 수 있습니다.

| 필드 | 설명 |
| --- | --- |
| `app_key` | 공개 App Key. |
| `action` | 비즈니스 장면. server_token 발급 시 사용한 action 과 일치해야 합니다. |
| `server_token` | 선택 사항이지만 앱에서 server_token_required = true 인 경우 필수입니다. |

::: info
대시보드에서 이 앱에 server_token_required 를 활성화한 경우, 인증 초기화 은 유효한 server_token 이 없는 요청을 거부합니다.
:::

## 오류 코드

| 코드 | 설명 |
| --- | --- |
| `invalid_app_key` | 유효하지 않은 App Key |
| `invalid_app_secret` | 유효하지 않은 App Secret |
| `challenge_expired` | Challenge 만료 |
| `challenge_not_found` | Challenge 를 찾을 수 없음 |
| `invalid_answer` | 유효하지 않은 정답 |
| `token_expired` | Token 만료 |
| `token_already_used` | Token 이미 사용됨 |
| `token_not_found` | Token 을 찾을 수 없음 |
| `quota_exceeded` | 할당량 초과 |
| `rate_limited` | 속도 제한됨 |
| `rate_limit_exceeded` | 이 앱의 발급 요청이 너무 많습니다. 잠시 후 다시 시도하세요. |