빠른 시작
키를 발급받고 첫 인증번호를 보낸 뒤 검증합니다.
이 문서는 서버에서 sk_ 비밀 키로 인증번호를 발급하고 검증하는 가장 짧은 경로를 안내합니다.
브라우저에서 직접 호출하려면 인증의 pk_ 키 설명을 함께 확인하세요.
콘솔에서 앱과 키 발급
콘솔에서 앱을 만들고 서버용 sk_ 키를 발급받습니다. 이 예제에는 otp:issue, otp:verify scope가 필요합니다.
발송하려면 앱 지갑에 크레딧이 있어야 합니다(크레딧과 결제).
키는 환경 변수로 보관하고 소스 코드나 클라이언트 번들에 넣지 마세요.
export KOTP_SECRET_KEY="sk_..."인증번호 발급
POST /v1/issue를 호출합니다. 모든 발급 요청에는 멱등 키가 필요합니다. 요청마다 새 키(예: UUID)를 만들고, 같은 요청을 재시도할 때는 반드시 같은 키를 다시 보냅니다.
curl -X POST "https://api.k-otp.dev/v1/issue" \
-H "Authorization: Bearer $KOTP_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b0f8f2e-3c1d-4d7a-9a2b-6f1e0c9d8a71" \
-d '{"phoneNumber":"01012345678","purpose":"login"}'성공 응답(200)에는 인증번호가 포함되지 않습니다. issueId를 사용자 세션 등에 저장해 두세요.
{
"issueId": "0192f3c4-8b7a-7c3e-9a51-2f4d6e8b1a90",
"expiresAt": "2026-09-28T03:03:00.000Z",
"attemptsRemaining": 5,
"queuedAt": "2026-09-28T03:00:00.000Z"
}선택 필드(채널, 템플릿, 만료 시간, 최대 시도 횟수 등)는 OTP 발급 레퍼런스를 참고하세요. 기본값은 SMS, 기본 템플릿(otp_default_kr), 만료 180초, 최대 5회 시도입니다.
인증번호 검증
사용자가 입력한 6자리 코드를 issueId와 함께 보냅니다.
curl -X POST "https://api.k-otp.dev/v1/verify" \
-H "Authorization: Bearer $KOTP_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"issueId":"0192f3c4-8b7a-7c3e-9a51-2f4d6e8b1a90","code":"123456"}'검증 실패도 HTTP 200으로 응답합니다. 반드시 verified 값을 확인하세요.
{
"issueId": "0192f3c4-8b7a-7c3e-9a51-2f4d6e8b1a90",
"verified": false,
"reasonCode": "MISMATCH",
"attemptsRemaining": 4,
"expiresAt": "2026-09-28T03:03:00.000Z"
}verified: true이면 인증 완료입니다. 성공한 issue는 다시 검증할 수 없습니다(1회성). 실패 사유별 처리는 발급 수명주기를 참고하세요.