K-OTP 소개

K-OTP는 휴대폰 인증번호(OTP)를 발급 → 발송 → 검증하는 과정을 API 두 번 호출로 끝낼 수 있게 해 주는 서비스입니다. 인증번호 생성, SMS·카카오 알림톡 발송, 만료·시도 횟수 관리, 중복 요청 방지, 크레딧 정산을 K-OTP가 처리합니다.

동작 방식

 서비스 서버/브라우저            K-OTP API                     최종 사용자 휴대폰
 ───────────────────            ─────────                     ─────────────────
 1. POST /v1/issue  ─────────▶  6자리 코드 생성 (해시만 저장)
    (Idempotency-Key)           크레딧 예약 + 발송 큐 등록
                     ◀───────── { issueId, expiresAt, ... }
                                2. SMS 또는 알림톡 발송 ─────▶  "[K-OTP] 인증번호는 123456..."
 3. POST /v1/verify ─────────▶  issueId + code 검증
    { issueId, code }           (만료·최대 시도·1회성 확인)
                     ◀───────── { verified: true }

발급(issue) — 서비스가 POST /v1/issue에 전화번호와 용도(purpose)를 보냅니다. K-OTP는 6자리 코드를 서버에서 생성하고, 크레딧을 예약한 뒤 발송을 큐에 넣습니다. 응답에는 코드가 아닌 issueId만 포함됩니다.
발송(deliver) — K-OTP가 SMS(기본값) 또는 알림톡으로 인증번호를 보냅니다. 발송 결과는 비동기로 추적되며 GET /v1/status로 확인할 수 있습니다.
검증(verify) — 사용자가 입력한 코드를 issueId와 함께 POST /v1/verify로 보냅니다. 결과는 항상 200이며 verified 값과 실패 사유(reasonCode)로 판단합니다.

핵심 개념

개념	설명
앱(app)	콘솔에서 만드는 단위입니다. 키, 크레딧 지갑, 발급 이력이 앱에 속합니다. 같은 앱의 키는 하나의 지갑을 공유합니다.
키	`pk_`(브라우저용 공개 키, 발급·검증 전용)와 `sk_`(서버 전용 비밀 키) 두 종류가 있습니다. 인증 참고.
issue	발급 한 건입니다. `issueId`로 식별하며 기본 3분 뒤 만료, 기본 5회까지 검증을 시도할 수 있습니다.
멱등 키	모든 발급 요청에 필요한 `Idempotency-Key`입니다. 재시도 시 중복 발송·중복 차감을 막습니다. 멱등성과 재시도 참고.
채널	SMS 또는 카카오 알림톡. 알림톡 발송이 실패하면 SMS로 자동 대체 발송됩니다. 채널과 대체 발송 참고.
크레딧	선불로 충전하는 발송 단위입니다. 대체 발송을 포함해 발송 1건에 1 크레딧이며, 잔액이 부족하면 발급이 `402`로 거절됩니다. 크레딧과 결제 참고.

주요 주소

용도	주소
API Base URL	`https://api.k-otp.dev/v1`
대화형 API 레퍼런스	https://api.k-otp.dev/docs
OpenAPI 스펙	https://api.k-otp.dev/openapi/v1.json
콘솔	https://app.k-otp.dev

다음 단계

빠른 시작

키를 발급받고 첫 인증번호를 보내고 검증합니다.

인증

pk_ / sk_ 키, Origin 허용 목록, scope

멱등성과 재시도

중복 발송 없이 안전하게 재시도하는 방법

API 레퍼런스

엔드포인트별 요청·응답·오류