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
• Go — go get github.com/Captcha-La/captchala-go

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

서버 측 Token 검증

프런트엔드 SDK 가 반환한 pass_token(pt_ 접두사)을 검증합니다. X-App-Key 와 X-App-Secret 헤더가 필요합니다.

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

{
  "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.

서버 발급 Challenge Token

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

Server Token 발급

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

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

{
  "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	이 앱의 발급 요청이 너무 많습니다. 잠시 후 다시 시도하세요.