콘솔 가이드

콘솔(app.k-otp.dev)은 K-OTP 앱과 키, 사용량, 크레딧을 관리하는 곳입니다. 모든 것은 조직에 속합니다. 조직은 팀이나 회사 단위이며 구성원, 앱, 크레딧 지갑 하나를 가집니다.

로그인

콘솔은 비밀번호를 쓰지 않습니다. 로그인 페이지에 이메일을 입력하면 로그인 링크와 6자리 코드가 담긴 이메일 한 통을 보내드립니다. 로그인 페이지에 코드를 입력하거나 링크를 여세요. 링크는 링크를 연 브라우저를 로그인시킵니다. 메일 앱이 링크를 다른 브라우저에서 열면 그 브라우저가 로그인되고 화면에 그렇게 안내됩니다. 로그인을 요청한 브라우저에서 계속하려면 그 브라우저에 코드를 입력하세요. 코드와 링크는 각각 한 번만 쓸 수 있고 15분 후 만료됩니다. 만료되었다면 새 이메일을 요청하세요(1분 후 다시 보낼 수 있습니다). Safari는 Apple Mail로 받은 코드를 자동으로 채워 줄 수 있습니다. 처음 로그인할 때 계정이 만들어지며, 바로 이어서 이름을 정할 수 있습니다. 조직 초대를 받았다면 초대받은 이메일로 로그인한 뒤 초대를 수락하세요. 초대가 없다면 이름을 정한 뒤 바로 조직을 만듭니다. 조직은 더 만들 수 있고 사이드바에서 전환할 수 있습니다. 계정 설정(프로필, 보안, 알림)은 사용자 메뉴에 있습니다.

앱

앱은 K-OTP를 사용하는 기본 단위입니다. 서비스(또는 환경)마다 앱을 하나씩 만드는 것을 권장합니다. 예를 들어 운영과 스테이징을 다른 앱으로 나누면 키와 사용량, 발급 이력이 섞이지 않습니다.

앱에 속하는 것:

• API 키(pk_, sk_)
• 발급 이력과 사용량

조직의 모든 앱은 조직 지갑의 크레딧을 함께 사용하며, 원장에서 차감마다 어느 앱이 사용했는지 확인할 수 있습니다.

키

앱 안에서 용도별로 키를 발급합니다.

• 서버용 sk_ 키 — 필요한 scope만 선택합니다. 발급·검증만 하는 서버라면 otp:issue, otp:verify, 관리 화면이나 정산 배치라면 otp:dashboard:read, otp:ledger:read, otp:balance 등을 추가합니다.
• 브라우저용 pk_ 키 — otp:issue, otp:verify만 가질 수 있으며, 호출을 허용할 Origin을 정확히 등록해야 합니다(예: https://www.example.com). 와일드카드는 지원하지 않습니다.

키마다 사용자 지정 속도 제한(키당, IP당, 휴대폰 번호당)을 둘 수 있으며, 키 목록에는 pk_ 플랫폼 기본값을 포함해 실제로 적용되는 제한이 표시됩니다. 자세한 내용은 인증 › 호출 제한을 참고하세요.

키 값은 비밀번호처럼 다루세요. 교체·폐기 절차와 반영 시간(최대 약 60초)은 인증 › 키 교체와 폐기를 참고하세요.

키 화면의 테스트 탭에는 앱의 테스트 키(pk_test_, sk_test_)가 있습니다. 테스트 키는 매직 테스트 번호만 받으며 아무것도 발송하거나 과금하지 않습니다. 테스트 발급은 사용량이나 발급 내역이 아니라 앱의 테스트 수신함에 고정 코드와 함께 표시됩니다. 테스트 모드를 참고하세요.

사용량

사용량 페이지는 조직의 모든 앱 사용량을 한국 시간(KST) 일자별로, 앱별 또는 채널별로 나눠 보여 줍니다. 앱마다 있는 사용량 페이지는 그 앱의 사용량을 UTC 일자별로 보여 줍니다. 발급 이력과 발송·검증 상태도 콘솔에서 확인할 수 있습니다. 같은 데이터는 API로도 조회할 수 있습니다.

• 발급 이력: GET /v1/issues, GET /v1/issues/{issueId}
• 단건 상태: GET /v1/status

이력에는 휴대폰 번호, 인증번호, 멱등 키, metadata 같은 민감 정보가 포함되지 않습니다.

크레딧

조직 소유자와 관리자는 콘솔에서 조직 지갑에 크레딧을 충전하고, 모든 구성원이 잔액과 변동 내역을 확인할 수 있습니다. 잔액이 부족하면 발급이 402 PAYMENT_REQUIRED로 거절되므로, 사용량에 맞춰 여유 있게 충전해 두세요. 자세한 내용은 크레딧과 결제를 참고하세요.