# 첫 인증 만들기

> 프로젝트 생성부터 첫 인증 결과 조회까지

문서: https://sendwich.kr/docs/quickstart/

## 1. 프로젝트 생성

1. [회원가입](https://sendwich.kr/signup/) 후 이메일 인증을 완료합니다.
2. [대시보드](https://sendwich.kr/dashboard/)에서 **프로젝트 만들기**를 선택하고 이름을 입력합니다.
3. 프로젝트의 **인증 체험**에서 문자를 보내 인증 결과를 확인합니다.

인증 체험은 실제 SMS 인증으로, 내역과 API 사용량에 반영되며 등록된 웹훅에도 결과를 전송합니다. 화면만 살펴보려면 [공개 데모](https://sendwich.kr/demo/)를 이용할 수 있습니다.

## 2. API 키 발급

프로젝트의 **API 키 → 새 키 만들기**에서 키를 발급합니다. 전체 키는 발급 시 한 번만 표시되므로 서버의 비밀 환경변수에 저장합니다.

```bash
# 서버의 비밀 환경변수 또는 비밀 관리 도구에서 설정해요.
export SENDWICH_API_KEY='YOUR_LIVE_SECRET_KEY'
```

## 3. 인증 생성

새 인증마다 고유한 `Idempotency-Key`를 사용합니다. 같은 요청을 재시도할 때는 키와 본문을 유지합니다.

```bash
curl 'https://api.sendwich.kr/v1/verifications' \
  -H "Authorization: Bearer $SENDWICH_API_KEY" \
  -H 'Idempotency-Key: quickstart_attempt_001' \
  -H 'Content-Type: application/json' \
  --data '{"mode":"discover","client_reference":"attempt_001"}'
```

응답의 `id`를 서버에 저장하고, 인증을 시작한 사용자 또는 가입 시도와 연결합니다. `client_reference`는 서비스에서 정한 시도 식별자입니다.

## 4. 문자 전송과 결과 조회

응답의 `verification_url`을 열거나, 직접 만든 화면에 `destination`, `sms_text`, `expires_at`을 표시합니다. 사용자가 안내된 번호로 인증 문자를 보내면 다음 API로 결과를 조회합니다.

```bash
# vrf_EXAMPLE을 방금 받은 id로 바꿔요.
curl 'https://api.sendwich.kr/v1/verifications/vrf_EXAMPLE' \
  -H "Authorization: Bearer $SENDWICH_API_KEY"
```

| `status` | 처리 |
| --- | --- |
| `verified` | `phone`에서 확인된 번호 조회 |
| `pending` | 문자 수신 대기 |
| `expired`, `cancelled` | 새 인증 시작 |

자동으로 결과를 받으려면 [웹훅](https://sendwich.kr/docs/webhooks/)을 설정합니다. 조회와 재시도는 각각 API 호출로 집계됩니다.

## 연동 예제

- [인증 창 연결하기](https://sendwich.kr/docs/verification-window/): 팝업과 모바일 전환
- [직접 만든 인증 화면](https://sendwich.kr/docs/examples/custom-ui/): 서비스 화면에서 인증 구현
- [Discord 봇](https://sendwich.kr/docs/examples/discord/): 비공개 메시지와 역할 부여
- [Node.js와 Python](https://sendwich.kr/docs/examples/node-python/): 서버 API 호출