콘텐츠로 이동

Hive OTP 인증 시스템

Hive OTP 인증 시스템은 게임에 OTP 인증을 적용할 수 있도록 OTP 발송과 OTP 검증으로 구성된 API를 제공합니다.

환경별 접근 URL

서버 URL
Production https://otp.qpyou.cn
Sandbox https://sandbox-otp.qpyou.cn

인증 방식

Hive OTP 발송 시스템이 제공하는 API를 사용하려면 먼저 인증 토큰(API KEY)을 발급받아야 합니다. 인증 토큰은 앱센터에 게임이 등록되면 자동으로 생성됩니다. 인증 토큰은 JWT(JSON Web Token: https://jwt.io) 명세를 따르며, 만료 시간이 없어 고정적으로 사용할 수 있습니다.

OTP 발송

OTP SMS 발송

  • Basic Info
Method POST
URL /otp/sms
  • Request Header
필드 타입
Content-Type application/json
Authorization bearer
Topic Hive 콘솔 노티피케이션 > SMS OTP > 발송 정보 설정에서 등록 또는 수정 > 발송 ID
  • OTP SMS를 앱 개발사가 직접 발송 시 콜백

Hive OTP에서 OTP SMS를 직접 발송하는 것이 아니라 OTP SMS를 개발사가 직접 발송하는 경우, 발송에 필요한 정보를 콜백으로 받을 수 있습니다. Hive 콘솔 > 노티피케이션 > SMS OTP > 발송 정보 설정에서 직접 발송을 선택하면, 등록한 콜백 URL로 아래 데이터가 Request Body에 JSON 형태로 전달됩니다. 콜백 요청 예시와 전달하는 데이터를 참고하세요.

  • Request Body
필드 타입 필수여부 설명
to String O 수신 전화번호
toCountryNo String O 수신 국가코드
retry Boolean X 이 API를 사용해 동일한 수신자에게 OTP SMS를 보내려고 시도한 이력이 있는지 여부입니다. 값이 주어지지 않으면, 최근 5분 이내에 동일한 수신자에게 OTP SMS를 전송 시도한 이력이 있을 때 true, 그렇지 않으면 false로 설정됩니다.
lookup Boolean X to 값이 유효한 전화번호 형식인지 검증할지 여부로 기본값은 false입니다. true일 때는 검증을 수행하므로 API 응답에 대략 250ms ~ 2000ms정도 소요되며, false일 때에는 보통 200ms 이내로 API 응답을 받습니다.
lang String X 언어 코드로 기본값은 en.
유효한 언어 코드
  • ko
  • en
  • ja
  • zh-cn
  • zh-tw
  • zh-hans
  • zh-hant
  • de
  • fr
  • ru
  • es
  • pt
  • id
  • th
  • vi
  • it
  • tr
  • ar
  • Response Header
필드 타입
Content-Type application/json
  • Response Body
필드 타입 설명
otp String OTP 번호
provider String SMS 제공자
expiry String OTP 유효시간
  • Request Sample
//sample 1
curl --location 'https://otp.qpyou.cn/otp/send' 
--header 'Authorization: Bearer AUTH_TOKNE_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "to" : "01012345678",
    "toCountryNo" : "82",
    "lang" : "ko"
}'
//sample 2
curl --location 'https://otp.qpyou.cn/otp/send' 
--header 'Authorization: Bearer AUTH_TOKNE_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "to" : "01012345678",
    "toCountryNo" : "82",
    "lang" : "ko",
    "retry" : true,
    "lookup" : true
}'
  • Response Sample
{
    "otp" : "123456",
    "provider" : "YOUR SMS PROVIDER",
    "expiry" : "2022-07-20T15:18:06.885195100+09:00[Asia/Seoul]"
}

콜백 예시

curl --location 'https://{your_callback_url}' 
--header 'Content-Type: application/json' 
--data '{
    "to":"01012345678",
    "toCountryNo":"82",
    "lang":"en",
    "retry":null,
    "lookup":false,
    "serviceName":"LocalTest",
    "otp":"809881",
    "provider":"DIRECTSEND",
    "expiry":"2024-06-26T11:36:29.680680500+09:00[Asia/Seoul]",
    "expiryTimestamp":1719369389680
}'

콜백 데이터 정보

이름 타입 필수 여부 설명
expiry String O OTP 유효시간
(예시: 2024-06-25T11:39:43.076573600+09:00[Asia/Seoul])
expiryTimestamp Long O OTP 유효시간 타임스탬프
(예시: 1719283183076)
lang String X 언어 코드로 기본값은 en
lookup boolean X to 값이 유효한 전화번호 형식인지 검증.
기본값은 false
otp String O OTP 번호
provider String O SMS 제공자,
직접 발송이므로 DIRECTSEND 고정값으로 전달됨
retry boolean X 재시도 여부
serviceName String O 발송 정보 설정 메뉴에서 설정한 발송 서비스 명(영문)
to String O 수신 전화번호
toCountryNo String O 수신 국가코드

OTP 이메일 발송

Method POST
URL /otp/email
  • Request Header
필드 타입
Content-Type application/json
Authorization bearer
Topic Hive 콘솔 노티피케이션 > SMS OTP > 벌송 정보 설정에서 등록 또는 수정 > 발송 ID
  • Request Body
필드 타입 필수여부 설명
sender String O 발신 이메일 주소
senderName String O 발신 이메일 이름
receiver String O 수신 이메일 주소
subject String O 이메일 제목
lang String X 언어 코드로 기본값은 en.
유효한 언어 코드
  • ko
  • en
  • ja
  • zh-cn
  • zh-tw
  • zh-hans
  • zh-hant
  • de
  • fr
  • ru
  • es
  • pt
  • id
  • th
  • vi
  • it
  • tr
  • ar
  • Response Header
필드 타입
Content-Type application/json
  • Response Body
필드 타입 설명
otp String OTP 번호
expiry String OTP 유효시간
  • Request Sample
//sample
curl --location 'https://otp.qpyou.cn/otp/email/send' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data-raw '{
    "sender" : "staging-no-reply@withhive.com",
    "senderName" : "YOUR SERVICE NAME",
    "receiver" : "com2us@com2us.com",
    "subject" : "OTP EMAIL SEND",
    "lang" : "ko"
}'
  • Response Sample
{
    "otp" : "123456",
    "expiry" : "2022-07-20T15:19:19.305116+09:00[Asia/Seoul]"
}

OTP 검증

Method POST
URL /otp/verify
  • Request Header
필드 타입
Content-Type application/json
Authorization bearer
Topic Hive 콘솔 노티피케이션 > SMS OTP > 벌송 정보 설정에서 등록 또는 수정 > 발송 ID
  • Request Body
필드 타입 필수여부 설명
toCountryNo String X 수신 국가번호 (OTP를 SMS로 수신한 경우 필수)
to String X 수신 전화번호 (OTP를 SMS로 수신한 경우 필수)
receiver String X 수신 이메일 (OTP를 이메일로 수신한 경우 필수)
otp String O 수신 OTP
  • Response Header
필드 타입
Content-Type application/json
  • Response Body
필드 타입 설명
result boolean OTP 검증 결과
  • Request Sample 1
// sample 1
curl --location 'https://otp.qpyou.cn/otp/verify' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "toCountryNo" : "82",
    "to" : "01036012891",
    "otp" : "123456"
}'
  • Request Sample 2
//sample 2
curl --location 'https://otp.qpyou.cn/otp/verify' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data-raw '{
    "receiver" : "com2us@com2us.com",
    "otp" : "123456"
}'
  • Response Sample
{
    "result" : true (or false)
}