K-OTP를 소개합니다

한국 사용자를 위한 휴대폰 인증번호 API, K-OTP를 출시합니다.

회원가입, 로그인, 연락처 변경처럼 사용자가 그 휴대폰 번호로 메시지를 받을 수 있는지 확인해야 하는 순간은 많습니다. 직접 만들려면 인증코드를 생성하고, 한국 사용자가 실제로 확인하는 채널로 보내고, 만료와 시도 횟수를 관리하고, 재시도한 요청이 메시지를 두 번 보내지 않도록 막아야 합니다. K-OTP는 이 과정을 두 번의 API 호출로 정리했습니다.

발급, 전달, 검증

발급. 서버(sk_ 키) 또는 웹 앱(pk_ 키)에서 휴대폰 번호, 용도(purpose), 멱등키로 POST /v1/issue를 호출합니다. K-OTP가 6자리 인증코드를 생성하고 issueId를 돌려줍니다.
전달. 인증코드는 카카오 알림톡 메시지로 사용자에게 전달됩니다. 발송 상태는 queued → sent → delivered 순으로 바뀌며, 서버에서 GET /v1/status로 확인할 수 있습니다. 도달은 메시지가 도착했다는 뜻이지, 인증이 끝났다는 뜻이 아닙니다.
검증. issueId와 사용자가 입력한 코드로 POST /v1/verify를 호출합니다. 코드가 일치할 때만 verified: true입니다. 기본값은 유효시간 3분, 시도 5회입니다.

로그인 처리, 번호 확인 표시, 재요청 등 다음 단계는 내 서비스가 정합니다. 검증 완료는 그 번호로 발송된 인증코드를 사용자가 확인해 입력했다는 뜻이며, 실명 확인이나 법적 본인확인이 아닙니다. 전달 방식은 채널 가이드에서 자세히 설명합니다.

재시도해도 한 번만

모든 발급 요청에는 멱등키가 필요합니다. 요청이 타임아웃되면 같은 키로 다시 보내세요. 같은 키와 같은 요청이면 첫 결과를 그대로 돌려주고, 메시지를 다시 보내거나 크레딧을 다시 차감하지 않습니다. 이미 쓴 키로 다른 요청을 보내면 409 CONFLICT로 거절합니다. 발송사의 결과가 불명확할 때도 K-OTP는 스스로 다시 보내지 않습니다. 사용자가 인증코드를 받지 못했다면, 사용자가 요청할 때 새로 발급하세요. 자세한 내용은 멱등성과 재시도를 참고하세요.

개인정보는 적게, 짧게

발급 기록에는 휴대폰 번호의 해시만 저장합니다. 인증코드도 해시로만 보관하고 API 응답에 넣지 않습니다. 발송 기록에는 메시지를 보내기 위해 수신 번호가 필요하므로 암호화해 저장하고, 발송이 최종 상태가 된 뒤 약 24시간이 지나면 지웁니다. 자세한 내용은 개인정보처리방침에 있습니다.

서버용 키와 브라우저용 키

서버에서는 sk_ 시크릿 키를, 브라우저에서는 pk_ 퍼블릭 키를 사용합니다. 퍼블릭 키는 미리 등록한 Origin에서만, 발급과 검증에만 쓸 수 있습니다.

선불 크레딧

OTP 발송 1건에 1 크레딧이며, 사용자가 인증을 마쳤는지와 관계없이 차감됩니다. 검증 호출은 무료입니다. 크레딧 팩에는 보너스 크레딧이 포함되고, 구독은 없으며, 구매한 크레딧은 만료되지 않습니다. 크레딧 지갑은 조직마다 하나이고 조직의 모든 앱이 함께 씁니다. 팩 구성은 요금 페이지에서 확인하세요.

시작하기

콘솔에서 계정을 만들고 앱과 키를 추가한 뒤 퀵스타트를 따라 하세요. JavaScript/TypeScript SDK @k-otp/sdk는 브라우저·서버 클라이언트, React·Vue·Svelte 바인딩, 헤드리스 UI 컴포넌트를 제공합니다. 모든 엔드포인트는 API 레퍼런스에 있습니다.