OAuth 權杖核發¶

呼叫 Hive Server API 時發出授權驗證和安全性身分驗證所需的 OAuth 令牌。 「頒發 OAuth 令牌」API 遵循 OAuth 2.0 用戶端憑證授予標準，並作為伺服器到伺服器驗證流程運行，其中應用程式伺服器直接呼叫 Hive 驗證伺服器。 「頒發 OAuth 令牌」API 具有以下特徵。 - 僅使用客戶端 ID 和金鑰頒發令牌 - 僅頒發存取令牌（不頒發刷新令牌） - 有效期限為 1 小時（3600 秒）

請求網址¶

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

身體¶

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

響應體¶

回應碼¶

回應範例¶

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

錯誤回應範例¶

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

如何使用代幣¶

呼叫 Hive Server API 時，將頒發的存取權令牌包含在 HTTP 標頭中。

JWT 令牌結構¶

簽發的Access Token採用JWT（JSON Web Token）格式，由三個部分組成，以句點（.）分隔：Header、Payload和Signature。

標題¶

標題設置¶

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 令牌驗證錯誤¶

當 Hive Server API 中的 JWT 令牌驗證失敗時，將透過 token_validation 欄位提供詳細的錯誤訊息。

token_validation 字段¶

此欄位包含JWT驗證錯誤訊息： | 欄位名稱 | 描述 | 類型 | | --- | --- | --- | | token_validation | JWT 驗證詳細資料 | Object | | token_validation.result_code | JWT驗證結果代碼詳情 | Integer | | token_validation.result_msg | JWT 驗證結果訊息 | String | ???+ note- JWT 驗證成功時：token_validation.result_code: 0 - JWT驗證失敗時：在token_validation.result_code中傳回詳細的錯誤代碼 - 此欄位通常由 Hive Server API 使用。

錯誤回應範例¶

沒有客戶訊息¶

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

缺少令牌¶

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

令牌簽署錯誤¶

"token_validation": {
  "result_code": 2407,
  "result_msg": "Invalid token signature."
}

過期令牌¶

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

JWT 驗證錯誤代碼¶

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

令牌更新¶

刷新令牌不是在客戶端憑證授予中頒發的。

處理令牌過期¶

1. Access Token過期（發出後1小時） 2.呼叫API時JWT驗證失敗（token_validation.result_code: 2408） 3.呼叫/oauth/token介面重新簽發新的Access Token

建議的代幣重用¶

訪問令牌可以重複使用，直到過期。 建議： - 建議：快取已發放的token並重複使用直至過期 - 不建議：為每個 API 呼叫發出新的令牌

安全建議¶

客戶端機密管理¶

客戶端密鑰是敏感訊息，必須安全管理。 | 項目 | 描述 | | --- | --- | | 切勿暴露 |切勿將客戶端密鑰暴露給客戶端（應用程式/網路） | | 僅限伺服器 |僅在遊戲伺服器上使用它（伺服器到伺服器通訊）| | 安全儲存 |將其儲存在環境變數或安全儲存（Vault）中 |

需要 HTTPS¶

頒發 OAuth Token 和呼叫 API 時必須使用 HTTPS。 - 建議：https://auth.qpyou.cn/oauth/token - 禁止：使用http://（容易受到中間人攻擊）