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://（容易受到中间人攻击）