Token Verification¶
The Token Verification API validates a token using the user token, Player ID, and DID(Instance ID) in the app client's login result, PlayerInfo. It operates through server-to-server communication from the app server directly to the Hive authentication server.
As long as your app does not allow duplicate logins, you can implement session management functionality that manages validated tokens or uses your app's own session keys.
The Token Verification API supports two methods depending on the JWT passed in X-Access-Token.
- User JWT method:
POST /v2/game/token/get-token - Project JWT method:
POST /v2/game/token/get-token-project
Both methods require the login result PlayerInfo.playerToken in Authorization.
Note
Hive authentication servers are configured in a distributed environment to protect against failures or network communication problems. If communication with the authentication server host is not possible or the timeout set by the app server is exceeded, the app server must directly call the distributed environment URL of the corresponding API. This applies to both methods supported by the Token Verification API.
User JWT method¶
Use the User JWT returned after the app client logs in successfully to verify the token. Pass PlayerInfo.accessToken in X-Access-Token.
Request URL¶
URLs for each environment below: POST Please request it using a method. The data format of the request body and response is JSON.
| environment | URL | HTTP Method | Content-Type |
|---|---|---|---|
| commercial | https://auth.qpyou.cn/v2/game/token/get-token | POST | application/json |
| distributed environment | https://auth.globalwithhive.com/v2/game/token/get-token | POST | application/json |
| Sandbox | https://sandbox-auth.qpyou.cn/v2/game/token/get-token | POST | application/json |
Request header¶
Pass the user token to verify in Authorization and the User JWT in X-Access-Token. Set ISCRYPT to 0, which indicates that encryption is not used.
| field name | Description | type | Required? |
|---|---|---|---|
Authorization | User token returned after successful login from the app client.PlayerInfo.playerToken | String | Y |
X-Access-Token | User JWT for user authentication. Returned after successful login PlayerInfo.accessToken | String | Y |
ISCRYPT | Whether your data is encrypted or not. surely 0pass to | Integer | Y |
Request body¶
Pass user identifying information from login results. include_fieldsIf you specify , the response's dataInclude additional information for that field.
| field name | Description | type | Required? |
|---|---|---|---|
appid | App ID | String | Y |
did | Instance ID returned after successful login | String | Y |
player_id | Authentication Player ID returned after successful login | BigInteger | Y |
include_fields | A list of fields for additional information to include in the response. Additional Field List See also | Array | N |
Additional Field List¶
Enter the required items in the fields below include_fields Specify it in an array.
| field name | Description | type | return value |
|---|---|---|---|
is_blocked | Is there any restriction on use? | Boolean | true: Sanctions, false: normal |
is_device_registered | Whether device management is enabled | Boolean | true: use, false: Not used |
join_timestamp | player_id Join date | Long | Unix Timestamp |
china_pi_no | Chinese real name authentication number | String / null | If real name authentication is not completed null |
Response body¶
result_codeCheck the token verification result with . If JWT verification fails token_validationCheck for detailed errors. What does the error mean? JWT validation error codeSee .
| field name | Description | type | location |
|---|---|---|---|
result_code | Result code. 0Verification was successful. response code See also | Integer | response body |
result_msg | Result message | String | response body |
token_validation | JWT verification result | Object | response body |
token_validation.result_code | JWT verification result code | Integer | token_validation sub |
token_validation.result_msg | JWT verification result message | String | token_validation sub |
data | Upon request include_fieldsAn object containing the information specified in | Object | response body |
response code¶
Based on the verification results, the code below is returned.
0: success2300: Subject to refund user repayment2499: JWT verification failed.token_validationSee also4000: Invalid parameter4001: Request JSON error5000:DB error6000: invalidappid6001: IdP token error7000: Invalid token7001:No token value in request header9999: unknown error
Request example¶
This is an example of a basic request and a body requesting additional information. The request header contains the token described above and ISCRYPTPlease include separately.
default request¶
Example request body with only required fields.
{
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"did": "255764404509548",
"player_id": 10000000000
}
Request more information¶
include_fieldsThis is an example of a body requesting four pieces of additional information.
{
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"did": "255764404509548",
"player_id": 10000000000,
"include_fields": ["is_blocked", "is_device_registered", "join_timestamp", "china_pi_no"]
}
Response example¶
This is an example of a successful token verification and response based on a request for additional information.
Verification successful¶
This is an example of a response where token verification was successful.
{
"result_code": 0,
"result_msg": "SUCCESS",
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
JWT validation failed¶
This is an example of a response where validation failed due to the JWT validity period expiring.
{
"result_code": 2499,
"result_msg": "JWT validation failed. See token_validation for details.",
"token_validation": {
"result_code": 2408,
"result_msg": "The access token is expired. Please refresh your token."
}
}
Includes additional information¶
include_fieldsInformation requested by dataThis is an example response included in .
{
"result_code": 0,
"result_msg": "SUCCESS",
"token_validation": {
"result_code": 0,
"result_msg": "success"
},
"data": {
"is_blocked": false,
"is_device_registered": false,
"join_timestamp": 1495594605,
"china_pi_no": null
}
}
Project JWT method¶
If there is no User JWT, the token is verified using the Project JWT issued by the app server. X-Access-Tokenin Issue OAuth TokenPass the Access Token for app server authentication issued by .
Request URL¶
URLs for each environment below: POST Please request it using a method. The data format of the request body and response is JSON.
| environment | URL | HTTP Method | Content-Type |
|---|---|---|---|
| commercial | https://auth.qpyou.cn/v2/game/token/get-token-project | POST | application/json |
| distributed environment | https://auth.globalwithhive.com/v2/game/token/get-token-project | POST | application/json |
| Sandbox | https://sandbox-auth.qpyou.cn/v2/game/token/get-token-project | POST | application/json |
Request header¶
User token and Project JWT to be verified respectively Authorizationand X-Access-TokenPlease pass it on to. ISCRYPTis a value that does not use encryption 0It must be passed on.
| field name | Description | type | Required? |
|---|---|---|---|
Authorization | User token returned after successful login from the app client. PlayerInfo.playerToken | String | Y |
X-Access-Token | Project JWT for app server authentication. Issue OAuth TokenOAuth 2.0 Access Token issued by | String | Y |
ISCRYPT | Whether your data is encrypted or not. surely 0pass to | Integer | Y |
Request body¶
Pass user identifying information from login results. include_fieldsIf you specify , the response'sdataInclude additional information for that field.
| field name | Description | type | Required? |
|---|---|---|---|
appid | App ID | String | Y |
did | Instance ID returned after successful login | String | Y |
player_id | Authentication Player ID returned after successful login | BigInteger | Y |
include_fields | A list of fields for additional information to include in the response. Additional Field List See also | Array | N |
Additional Field List¶
Enter the required items in the fields below include_fields Specify it in an array.
| field name | Description | type | return value |
|---|---|---|---|
is_blocked | Is there any restriction on use? | Boolean | true: Sanctions, false: normal |
is_device_registered | Whether device management is enabled | Boolean | true: use, false: Not used |
join_timestamp | player_id Join date | Long | Unix Timestamp |
china_pi_no | Chinese real name authentication number | String / null | If real name authentication is not completed null |
Response body¶
result_codeCheck the token verification result with . If JWT verification fails token_validationCheck for detailed errors. What does the error mean? JWT validation error codeSee .
| field name | Description | type | location |
|---|---|---|---|
result_code | Result code. 0Verification was successful. response code See also | Integer | response body |
result_msg | Result message | String | response body |
token_validation | JWT verification result | Object | response body |
token_validation.result_code | JWT verification result code | Integer | token_validation sub |
token_validation.result_msg | JWT verification result message | String | token_validation sub |
data | Upon request include_fieldsAn object containing the information specified in | Object | response body |
response code¶
Based on the verification results, the code below is returned.
0: success2300: Subject to refund user repayment2499: JWT verification failed.token_validationSee also4000: Invalid parameter4001: Request JSON error5000:DB error6000: invalidappid6001: IdP token error7000: Invalid token7001:No token value in request header9999: unknown error
Request example¶
This is an example of a basic request and a body requesting additional information. The request header contains the token described above and ISCRYPTPlease include separately.
default request¶
Example request body with only required fields.
{
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"did": "255764404509548",
"player_id": 10000000000
}
Request more information¶
include_fieldsThis is an example of a body requesting four pieces of additional information.
{
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"did": "255764404509548",
"player_id": 10000000000,
"include_fields": ["is_blocked", "is_device_registered", "join_timestamp", "china_pi_no"]
}
Response example¶
This is an example of a successful token verification and response based on a request for additional information.
Verification successful¶
This is an example of a response where token verification was successful.
{
"result_code": 0,
"result_msg": "SUCCESS",
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
JWT validation failed¶
This is an example of a response where validation failed due to the JWT validity period expiring.
{
"result_code": 2499,
"result_msg": "JWT validation failed. See token_validation for details.",
"token_validation": {
"result_code": 2408,
"result_msg": "The access token is expired. Please refresh your token."
}
}
Includes additional information¶
include_fieldsInformation requested by dataThis is an example response included in .