Issue OAuth token¶

Issues an OAuth token required for authorization validation and secure authentication when calling Hive Server APIs.

The 'Issue OAuth token' API follows the OAuth 2.0 Client Credentials Grant standard and operates as a Server-to-Server authentication flow, where the app server calls the Hive authentication server directly.

The 'Issue OAuth token' API has the following characteristics.

• Issues a token using only the Client ID and Secret
• Issues only an Access Token (no Refresh Token is issued)
• Valid for 1 hour (3600 seconds)

Request URL¶

Request header¶

Request body¶

Request example¶

curl¶

curl -X POST https://auth.qpyou.cn/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "grant_type": "client_credentials",
    "client_id": "project_abc123",
    "client_secret": "secret_xyz789"
  }'

Body¶

{
  "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
  "grant_type": "client_credentials",
  "client_id": "project_abc123",
  "client_secret": "secret_xyz789"
}

Response body¶

Response code¶

Response example¶

{
  "result_code": 0,
  "result_msg": "SUCCESS",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0.eyJwcm9qZWN0X2lkIjoiY29tLmNvbTJ1cy5leGFtcGxlIiwidG9rZW5fdHlwZSI6ImFjY2Vzc190b2tlbiIsImdyYW50X3R5cGUiOiJwcm9qZWN0IiwiaWF0IjoxNzE1NTg0MDAwLCJleHAiOjE3MTU1ODc2MDAsImF1dGhfdmVyIjoidjQiLCJ1c2VyX2lkIjoiIiwiaXNfd2hpdGVsaXN0Ijp0cnVlfQ.signature"
  }
}

Error response example¶

{
  "result_code": 4001,
  "result_msg": "INVALID_CLIENT",
  "data": null
}

How to use the token¶

Include the issued Access Token in the HTTP header when calling Hive Server APIs.

JWT token structure¶

The issued Access Token is in JWT (JSON Web Token) format and consists of three parts separated by periods (.): Header, Payload, and Signature.

Header¶

Payload¶

Header settings¶

Usage example¶

curl -X POST https://auth.qpyou.cn/v2/game/player/get-idp \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..." \
  -H "ISCRYPT: 0" \
  -d '{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "player_id": 123456789
  }'

JWT token validation errors¶

When JWT token validation fails in Hive Server APIs, detailed error information is provided through the token_validation field.

token_validation field¶

This field contains JWT validation error information:

Error response examples¶

No client information¶

"token_validation": {
  "result_code": 2400,
  "result_msg": "No client information found."
}

Missing token¶

"token_validation": {
  "result_code": 2406,
  "result_msg": "The access token is missing."
}

Token signature error¶

"token_validation": {
  "result_code": 2407,
  "result_msg": "The JWT signature verification failed."
}

Expired token¶

"token_validation": {
  "result_code": 2408,
  "result_msg": "The access token is expired. Please refresh your token."
}

JWT validation error codes¶

Normal response¶

When JWT validation succeeds:

"token_validation": {
  "result_code": 0,
  "result_msg": "success"
}

Token renewal¶

Refresh Tokens are not issued in the Client Credentials Grant.

Handling token expiration¶

1. The Access Token expires (1 hour after issue)
2. JWT validation fails when calling the API (token_validation.result_code: 2408)
3. Call the /oauth/token API to reissue a new Access Token

Recommended token reuse¶

The Access Token can be reused until it expires.

Recommendations:

• Recommended: Cache the issued token and reuse it until it expires
• Not recommended: Issue a new token for every API call

Security recommendations¶

Client secret management¶

Client Secret is sensitive information and must be managed securely.

HTTPS required¶

You must use HTTPS when issuing OAuth Tokens and calling APIs.

• Recommended: https://auth.qpyou.cn/oauth/token
• Prohibited: using http:// (vulnerable to man-in-the-middle attacks)