API 두 번
발급하고, 검증하면 끝.
모든 발급 요청에는 멱등키가 붙습니다. 요청이 타임아웃되면 같은 키로 다시 보내세요. 문자가 한 번 더 가는 대신 처음 응답을 그대로 받습니다.
# 1. 인증번호 발급 — 재시도할 때는 같은 키를 재사용curl https://api.k-otp.dev/v1/issue \ -H "Authorization: Bearer $KOTP_SECRET_KEY" \ -H "Idempotency-Key: signup-3f2a9c1e-0001" \ -H "Content-Type: application/json" \ -d '{ "phoneNumber": "01012345678", "purpose": "signup", "channel": "alimtalk", "templateId": "otp_signup_kr" }'# 응답 → { "issueId": "5b1f3c2e-…", "attemptsRemaining": 5, "expiresAt": "…" }# 2. 사용자가 입력한 코드 검증curl https://api.k-otp.dev/v1/verify \ -H "Authorization: Bearer $KOTP_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "issueId": "5b1f3c2e-8d4a-4f7e-9a61-2c0d7e9b4a10", "code": "482913" }'# 응답 → { "issueId": "5b1f3c2e-…", "verified": true, "verifiedAt": "…" }제품
OTP에서 꼭 문제가 되는 부분을 위해
한국의 문자 발송에는 고유한 채널과 재시도 함정이 있습니다. K-OTP는 두 개의 엔드포인트 뒤에서 이를 처리합니다.
SMS와 알림톡, 하나의 API
요청마다 채널과 등록된 템플릿을 고르세요. 알림톡 발송에 실패하면 SMS로 자동 대체 발송하며, 이때도 1 크레딧만 차감됩니다.
멱등키와 안전한 재시도
같은 키와 같은 요청은 첫 결과를 돌려줍니다. 결과가 불명확한 발송은 자동으로 다시 보내지 않습니다.
보여줄 수 있는 발송 상태
GET /v1/status는 검증 상태와 도달 상태를 하나의 overallStatus로 합쳐 CS 대응을 돕습니다.
pk_ · sk_ 키 분리
퍼블릭 키는 허용한 Origin에서만, 브라우저에서 발급·검증만 호출합니다. 시크릿 키는 서버에만 두세요.
선불 크레딧
한 번 충전하고, 채널과 관계없이 OTP 발송 1건에 1 크레딧만 쓰세요. 잔액과 원장은 API로 확인할 수 있습니다. 예상치 못한 청구서가 없습니다.
OpenAPI 기반 문서
서버가 실제로 강제하는 계약에서 생성한 OpenAPI 3.1 스펙과 API 레퍼런스를 제공합니다.
동작 방식
가입부터 첫 인증 완료까지
01
키 만들기
콘솔에 가입하고 서버용 sk_ 키 또는 웹 앱용 pk_ 키를 발급하세요.
02
멱등키와 함께 발급
전화번호, 용도, 멱등키로 POST /v1/issue를 호출합니다. 6자리 코드는 서버에서 생성됩니다.
03
발송과 상태 추적
메시지는 큐를 거쳐 SMS 또는 알림톡으로 나가며, 알림톡이 실패하면 SMS로 자동 대체 발송됩니다. 상태는 대기 → 발송 → 도달 순으로 바뀝니다.
04
한 번만 검증
issueId와 코드로 POST /v1/verify를 호출합니다. 기본값은 유효시간 3분, 시도 5회입니다.
보안 · 개인정보
최소한만, 최대한 짧게 보관합니다.
OTP는 본인 확인 인프라입니다. 기본 설정은 침해 시도를 전제로 설계했습니다.
발급 기록에 전화번호 원문 미저장
발급 기록에는 전화번호의 해시만 남기며, 어떤 API 응답도 전화번호를 돌려주지 않습니다.
해시로 저장되는 일회용 코드
인증번호는 솔트를 더한 해시로만 저장되고, API로 반환되지 않으며, 검증에 성공하면 소진됩니다.
발송 개인정보는 암호화 후 파기
발송 기록의 수신자 정보는 암호화되어 저장되고, 최종 상태 후 약 24시간이 지나면 지워집니다.
브라우저 키는 허용 Origin에 고정
pk_ 키는 Origin이 정확히 일치해야 하며 발급과 검증만 할 수 있습니다.