Hive OTP 인증 시스템 – Developer guides

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 {API KEY}

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

필드	타입
Content-Type	application/json
Authorization	bearer {API KEY}
Topic	Hive 콘솔 노티피케이션 > SMS OTP > 발송 정보 설정에서 등록 또는 수정 > 발송 ID

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 유효시간

필드	타입
Content-Type	application/json

필드	타입	설명
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
}'

//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]" }

1
2
3
4
5

{
    "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
}'

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 {API KEY}

Topic Hive 콘솔 노티피케이션 > SMS OTP > 벌송 정보 설정에서 등록 또는 수정 > 발송 ID

필드	타입
Content-Type	application/json
Authorization	bearer {API KEY}
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 유효시간

필드	타입
Content-Type	application/json

필드	타입	설명
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"
}'

//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]" }

1
2
3
4

{
"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 {API KEY}

Topic Hive 콘솔 노티피케이션 > SMS OTP > 벌송 정보 설정에서 등록 또는 수정 > 발송 ID

필드	타입
Content-Type	application/json
Authorization	bearer {API KEY}
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 검증 결과

필드	타입
Content-Type	application/json

필드	타입	설명
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"
}'

// 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"
}'

//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) }

1
2
3

{
"result" : true (or false)
}

환경별 접근 URL

인증 방식

OTP 발송

OTP SMS 발송

OTP 이메일 발송

OTP 검증

시작하기

SDK 개발

콘솔 가이드

다운로드

API 문서

지원