OAuth トークン発行¶

Hive サーバー API を呼び出す際の認可検証と安全な認証に必要な OAuth トークンを発行します。 「OAuth トークンの発行」API は、OAuth 2.0 クライアント資格情報付与標準に従い、アプリサーバーが Hive 認証サーバーを直接呼び出すサーバー間認証フローとして動作します。 「OAuthトークン発行」APIには以下の特徴があります。 - クライアントIDとシークレットのみを使用してトークンを発行します ・アクセストークンのみ発行（リフレッシュトークンは発行されません） - 1時間(3600秒)有効

リクエスト URL¶

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 サーバー API を呼び出すときに、発行されたアクセス トークンを HTTP ヘッダーに含めます。

JWT トークン構造¶

発行されるアクセス トークンは JWT (JSON Web Token) 形式であり、ピリオド (.) で区切られたヘッダー、ペイロード、署名の 3 つの部分で構成されます。

ヘッダー¶

ヘッダー設定¶

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 サーバー 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 サーバー 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. アクセス トークンの有効期限が切れます (発行後 1 時間)。
2. API の呼び出し時に JWT 検証が失敗する (token_validation.result_code: 2408)
3. /oauth/token API を呼び出して、新しいアクセス トークンを再発行します。

推奨されるトークンの再利用¶

アクセス トークンは、有効期限が切れるまで再利用できます。 推奨事項: - 推奨: 発行されたトークンをキャッシュし、有効期限が切れるまで再利用します。 - 非推奨: API 呼び出しごとに新しいトークンを発行する

セキュリティに関する推奨事項¶

クライアント シークレットの管理¶

クライアント シークレットは機密情報であるため、安全に管理する必要があります。 | アイテム | 説明 | | --- | --- | | 決して公開しないでください |クライアント シークレットをクライアント (アプリ/ウェブ) に決して公開しないでください。 | | サーバーのみ |ゲームサーバー上でのみ使用します（サーバー間通信） | | 安全なストレージ |環境変数または安全なストレージ (Vault) に保存します。 |

HTTPSが必要です¶

OAuth トークンを発行して API を呼び出すときは、HTTPS を使用する必要があります。 - 推奨: https://auth.qpyou.cn/oauth/token - 禁止: http:// の使用 (中間者攻撃に対して脆弱)