---
title: 빠른 시작
---

# 빠른 시작

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

::: tip 30초 만에 실제 동작 확인
[demo-v1.captcha.la](https://demo-v1.captcha.la) — 순수 HTML + PHP, MIT 라이선스, 모든 페이지 view-source 가능.

- [popup.html](https://demo-v1.captcha.la/popup.html) — 팝업 모드
- [float.html](https://demo-v1.captcha.la/float.html) — 플로팅
- [bind.html](https://demo-v1.captcha.la/bind.html) — 버튼 바인딩
- [inline.html](https://demo-v1.captcha.la/inline.html) — 인라인 임베드
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — 서버 발급 토큰 (재전송 방지)
:::


## 1. 계정 만들기

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

[지금 가입하기 →](https://dash.captcha.la/register)

## 2. 애플리케이션 만들기

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

## 3. SDK 설치

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

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

```bash
# or via npm
npm install captchala
```

## 4. CAPTCHA 초기화

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

```html
<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. 서버 검증

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

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

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "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 모드 (프로덕션 권장) {#server-token}

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

### 사용 시점

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

### 1. 백엔드에서 server_token 발급

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

```bash
# 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 초기화 시 인증 초기화 으로 이를 전달합니다.

```js
// 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](./web-sdk)
- [API 레퍼런스](./api-reference)