APIリファレンス

CaptchaLaはRESTful APIインターフェースを提供し、すべての機能のサーバー側呼び出しをサポートします。

APIベース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 で boilerplate を省略。 エンドポイント・リトライ・型付きエラーをラップ:

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

サーバー発行チャレンジトークン

バックエンドから短寿命の server_token を発行し、ブラウザが初期化時にそれを送信することで、リクエストが信頼できるサーバー由来であることを証明します。

server_token を発行

自社サーバーからのみ呼び出し可能。X-App-Key と X-App-Secret が必要です。レスポンスに sct_ で始まる server_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	トークン有効期間（秒）。デフォルト 300、最大 900。
max_uses	最大消費回数。デフォルト 10。
bind_ip	指定の IP にトークンを紐付け。
bind_device_id	指定のデバイス ID に紐付け。
bind_fingerprint	指定のブラウザ指紋に紐付け。

チャレンジ初期化

SDK がチャレンジ開始時に呼び出します。/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	このアプリへの発行リクエストが多すぎます。時間を空けて再試行してください。