One-time password (OTP) API¶

The one-time password (OTP) authentication system provides APIs for OTP sending and OTP verification, allowing you to apply OTP authentication to your game.

URL¶

Authentication methods¶

To use the APIs provided by the OTP sending system, you must first obtain an authentication token (API KEY). The authentication token is created automatically when the game is registered in App Center. The authentication token follows the JSON Web Token (JWT) specification and can be used indefinitely because it has no expiration time.

Send OTP¶

Send OTP messages via short message service (SMS)¶

• Basic Info

• Request Header

• Callback required when you send OTP SMS directly

If the app developer sends OTP SMS messages directly instead of having the OTP system send them, you can receive the information required for sending via a callback. If you select Direct sending in Hive Console > Notification > SMS OTP > Sending information settings, the data below is delivered in JSON format in the request body to the registered callback URL. For the setup procedure, see Direct sending. Also review the sample callback request and the data sent.

• Request Body

• Response Header

• Response Body

• Request Sample

The following example shows how to call the OTP SMS sending API with the Topic header and recipient information.

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

When an OTP SMS sending request is processed successfully, you receive the following response body.

{
    "otp" : "123456",
    "provider" : "YOUR_SMS_PROVIDER",
    "expiry" : "2026-03-23T11:00:48.533695818+09:00",
    "expiryTimestamp" : 1774231248
}

Callback example¶

If the app developer is configured for direct sending, the registered callback URL receives the following request body.

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

Callback data informaton¶

Error response codes¶

When the Topic value is invalid¶

This error occurs when the Topic value in the request header does not match the Sending ID registered in Hive Console. Check the Topic header value and the Sending ID registered in Hive Console > Notification > SMS OTP > Sending information settings.

{
    "id" : 42202,
    "error" : "NO_TOPIC",
    "reason" : "No such 'Topic' Data"
}

When the same OTP is generated twice¶

If you send the same request twice within the same time window, the same OTP is generated. In this case, the first request succeeds and the second fails with DUPLICATE_OTP_EXISTS. Send the same request again in the next time window after the current one ends.

{
    "id" : 40902,
    "error" : "DUPLICATE_OTP_EXISTS",
    "reason" : "Already sent OTP to this phone number."
}

When the 24-hour sending limit is exceeded¶

This error occurs when the number of sends allowed to the same phone number within 24 hours is exceeded. This limit is not fixed. The count in the response message in the example below is only an example of the configured limit value. Check the daily sending limit in Hive Console > Notification > SMS OTP > Sending information settings.

{
    "id" : 42903,
    "error" : "SMS_LIMIT_EXCEEDED",
    "reason" : "Too many requests in 24 hours. (Can not exceed 10 times)"
}

Verify OTP¶

• Request Header

• Request Body

• Response Header

• Response Body

• Request Sample 1

The following example shows how to verify an OTP by passing the recipient phone number and OTP code.

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

• Response Sample

If the OTP matches, the response body is as follows.

{
    "result" : true
}