빠른 시작

이 가이드는 5분 안에 CaptchaLa CAPTCHA를 통합할 수 있도록 도와줍니다.

30초 만에 실제 동작 확인

demo-v1.captcha.la — 순수 HTML + PHP, MIT 라이선스, 모든 페이지 view-source 가능.

• popup.html — 팝업 모드
• float.html — 플로팅
• bind.html — 버튼 바인딩
• inline.html — 인라인 임베드
• server-token.html — 서버 발급 토큰 (재전송 방지)

1. 계정 만들기

대시보드에서 무료 계정을 등록합니다

지금 가입하기 →

2. 애플리케이션 만들기

대시보드에서 앱을 만들고 App Key를 받습니다

3. SDK 설치

원하는 설치 방식을 선택합니다

<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# or via npm
npm install captchala

4. CAPTCHA 초기화

페이지에서 CAPTCHA 컴포넌트를 초기화합니다

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. 서버 검증

서버에서 토큰을 검증합니다

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Always check data.valid === true and data.action matches the scene you expected. Pass tokens are single-use; the same pt_xxx cannot be validated twice.

서버 발급 Token 모드 (프로덕션 권장)

민감한 동작(로그인, 회원가입, 결제)에는 서버 발급 token 플로우를 권장합니다. 백엔드가 먼저 짧은 수명의 server_token 을 요청하고, 브라우저가 이 token으로 CAPTCHA를 초기화합니다. 이렇게 하면 app_key 유출로 인한 남용을 막을 수 있습니다.

사용 시점

• 권장: 회원가입, 로그인, 비밀번호 재설정, 결제, 포인트 교환, 그리고 공격자가 스크립트화할 수 있는 모든 엔드포인트.
• 선택 사항: 편의성이 더 중요한 공개 폼, 검색창, 저가치 상호작용.

1. 백엔드에서 server_token 발급

자체 서버에서 X-App-Key 와 X-App-Secret 헤더를 사용해 /v1/server/challenge/issue 를 호출하세요. 이 헤더를 브라우저에 노출해서는 안 됩니다.

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. 프런트엔드가 server_token 으로 CaptchaLa 렌더링

CaptchaLa 컴포넌트에 token을 전달하세요. SDK는 challenge 초기화 시 인증 초기화 으로 이를 전달합니다.

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

보안 참고

• app_secret 을 프런트엔드 코드, 모바일 앱, 공개 저장소에 두지 마세요. 반드시 서버 측에만 보관해야 합니다.
• 대시보드에서 "서버 발급 challenge token 요구"를 활성화하면 server_token 없이 시도된 모든 challenge를 거부할 수 있습니다.
• ttl 은 짧게 유지하고(기본 300초, 최대 900초), token 유출 영향을 줄이기 위해 max_uses=1 을 권장합니다.

다음 단계

• Web SDK
• API 레퍼런스