API 参考

CaptchaLa 提供 RESTful API 接口，支持所有功能的服务端调用。

API 地址

https://apiv1.captcha.la

认证方式

所有 API 请求需要在 Header 中携带认证信息：

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 省去 boilerplate。 封装端点 + 重试 + 类型化错误:

• PHP — Captcha-La/captchala-php
• Go — go get github.com/Captcha-La/captchala-go · README

在用户通过前端验证码后，您的服务端需要验证 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.

服务端签发验证 Token

由您的服务端签发短时效 server_token，再由浏览器在初始化挑战时携带该 Token，从而证明请求来自受信任的服务端。

签发 server_token

仅允许从您的服务端调用。需要 X-App-Key + X-App-Secret。响应返回 server_token（前缀 sct_），前端需在 验证初始化 时带上该 Token。

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 绑定到指定浏览器指纹。

初始化挑战

由 SDK 调用以开始一次验证码挑战。可选参数 server_token 由 /v1/server/challenge/issue 签发。

字段	说明
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_not_found	验证码不存在
invalid_answer	答案错误
token_expired	Token 已过期
token_already_used	Token 已被使用
token_not_found	Token 不存在
quota_exceeded	配额已用尽
rate_limited	请求频率超限
rate_limit_exceeded	该应用的签发请求过于频繁，请稍后重试。