トークン検証¶
「トークン検証」APIは、アプリクライアントのログイン結果である PlayerInfo のユーザートークン、Player ID、DID(Instance ID)を使用してトークンの有効性を検証します。アプリサーバーからHive認証サーバーを直接呼び出すサーバー間通信方式で動作します。
アプリが冗長ログインを許可していない場合にのみ、検証したトークンを管理したり、アプリ独自のセッションキーを使用したセッション管理機能を実装したりできます。
「トークン検証」APIは、X-Access-Token に使用するJWTに応じて2つの方式をサポートします。
- User JWT方式:
POST /v2/game/token/get-token - Project JWT方式:
POST /v2/game/token/get-token-project
どちらの方法も Authorizationにはログイン結果の PlayerInfo.playerTokenが必要です。
Note
Hive認証サーバーは、障害やネットワーク通信の問題に備えて分散環境で構成されています。認証サーバーホストと通信できない場合、またはアプリサーバーで設定したタイムアウトを超える場合は、アプリサーバーからそのAPIの分散環境URLを直接呼び出す必要があります。これは、トークン検証APIでサポートされている両方の方法に共通です。
User JWT方式¶
アプリクライアントのログイン成功時に返されるUser JWTを使用してトークンを検証します。X-Access-Token に PlayerInfo.accessTokenを渡してください。
Request URL¶
以下の環境固有のURLに POST メソッドでリクエストしてください。リクエスト本文とレスポンスのデータ型はJSONです。
| 環境 | URL | HTTP Method | Content-Type |
|---|---|---|---|
| 商業 | https://auth.qpyou.cn/v2/game/token/get-token | POST | application/json |
| 分散環境 | 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¶
検証するユーザートークンを Authorization に、User JWTを X-Access-Token に渡してください。ISCRYPT には暗号化を使用しないことを示す 0 を渡します。
| フィールド名 | 説明 | タイプ | 必須かどうか |
|---|---|---|---|
Authorization | アプリクライアントでログインが成功した後に返されたユーザートークン。PlayerInfo.playerToken | String | Y |
X-Access-Token | ユーザー本人認証のためのUser JWT。ログイン成功後に返された PlayerInfo.accessToken | String | Y |
ISCRYPT | データを暗号化するかどうか。必ず 0に渡す | Integer | Y |
Request body¶
ログイン結果のユーザー識別情報を渡します。 include_fieldsを指定すると、 dataにそのフィールドの追加情報が含まれます。
| フィールド名 | 説明 | タイプ | 必須かどうか |
|---|---|---|---|
appid | App ID | String | Y |
did | ログイン成功後に返されたインスタンスID | String | Y |
player_id | ログイン成功後に返された認証 Player ID | BigInteger | Y |
include_fields | 応答に追加する情報のフィールドのリスト。 追加フィールドのリスト 参考 | Array | N |
追加フィールドのリスト¶
以下のフィールドのうち必要な項目 include_fields 配列に割り当ててください。
| フィールド名 | 説明 | タイプ | 戻り値 |
|---|---|---|---|
is_blocked | 利用制限の有無 | Boolean | true:制裁、 false: 通常 |
is_device_registered | デバイス管理を有効にするかどうか | Boolean | true:使用、 false:未使用 |
join_timestamp | player_id 登録日 | Long | Unix Timestamp |
china_pi_no | 中国実名認証番号 | String / null | 本名認証が完了していない場合 null |
Response body¶
result_codeでトークン検証結果を確認してください。 JWT検証に失敗した場合 token_validationで詳細エラーを確認してください。エラーの意味は JWT検証エラーコードをご覧ください。
| フィールド名 | 説明 | タイプ | 場所 |
|---|---|---|---|
result_code | 結果コード。 0は検証成功。 レスポンスコード 参考 | Integer | 応答本文 |
result_msg | 結果メッセージ | String | 応答本文 |
token_validation | JWT検証結果 | Object | 応答本文 |
token_validation.result_code | JWT検証結果コード | Integer | token_validation 子 |
token_validation.result_msg | JWT検証結果メッセージ | String | token_validation 子 |
data | リクエストに応じて include_fieldsに指定した情報を含むオブジェクト | Object | 応答本文 |
レスポンスコード¶
検証結果に応じて、以下のコードを返します。
0: 成功2300: 払い戻しユーザーの再決済対象2499:JWT検証に失敗しました。token_validation参考4000: 無効なパラメータ4001: リクエストJSONエラー5000: DBエラー6000: 無効appid6001: IdP トークンエラー7000: 無効なトークン7001: 要求ヘッダーにトークン値がない9999:不明なエラー
Request example¶
基本要求と追加情報を要求する本文の例です。リクエストヘッダには、上記のトークンと ISCRYPTを別途含めてください。
基本リクエスト¶
必須フィールドのみを含む要求本文の例です。
{
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"did": "255764404509548",
"player_id": 10000000000
}
追加情報のリクエスト¶
include_fieldsとして4つの追加情報を要求する本文の例です。
{
"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¶
トークン検証が成功したかどうか、および追加情報の要求による応答の例。
検証成功¶
トークン検証に成功した応答の例です。
{
"result_code": 0,
"result_msg": "SUCCESS",
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
JWT検証失敗¶
JWT の有効期限が切れて検証に失敗した応答の例です。
{
"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."
}
}
追加情報を含める¶
include_fieldsとして要求された情報 dataに含まれる応答の例です。
{
"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方式¶
User JWTがない場合は、アプリサーバーから発行されたProject JWTを使用してトークンを検証します。 X-Access-Tokenに OAuth Tokenを発行するで発行されたアプリサーバー認証用のAccess Tokenを渡します。
Request URL¶
以下の環境固有のURLに POST メソッドでリクエストしてください。リクエスト本文とレスポンスのデータ型はJSONです。
| 環境 | URL | HTTP Method | Content-Type |
|---|---|---|---|
| 商業 | https://auth.qpyou.cn/v2/game/token/get-token-project | POST | application/json |
| 分散環境 | 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¶
検証するユーザートークンとProject JWTをそれぞれ Authorizationと X-Access-Tokenに渡してください。 ISCRYPTは暗号化を使用しない値です 0に渡す必要があります。
| フィールド名 | 説明 | タイプ | 必須かどうか |
|---|---|---|---|
Authorization | アプリクライアントでログインが成功した後に返されたユーザートークン。 PlayerInfo.playerToken | String | Y |
X-Access-Token | アプリサーバー認証用のProject JWT。 OAuth Tokenを発行するから発行されたOAuth 2.0 Access Token | String | Y |
ISCRYPT | データを暗号化するかどうか。必ず 0に渡す | Integer | Y |
Request body¶
ログイン結果のユーザー識別情報を渡します。 include_fieldsを指定すると、dataにそのフィールドの追加情報が含まれます。
| フィールド名 | 説明 | タイプ | 必須かどうか |
|---|---|---|---|
appid | App ID | String | Y |
did | ログイン成功後に返されたインスタンスID | String | Y |
player_id | ログイン成功後に返された認証 Player ID | BigInteger | Y |
include_fields | 応答に追加する情報のフィールドのリスト。 追加フィールドのリスト 参考 | Array | N |
追加フィールドのリスト¶
以下のフィールドのうち必要な項目 include_fields 配列に割り当ててください。
| フィールド名 | 説明 | タイプ | 戻り値 |
|---|---|---|---|
is_blocked | 利用制限の有無 | Boolean | true:制裁、 false: 通常 |
is_device_registered | デバイス管理を有効にするかどうか | Boolean | true:使用、 false:未使用 |
join_timestamp | player_id 登録日 | Long | Unix Timestamp |
china_pi_no | 中国実名認証番号 | String / null | 本名認証が完了していない場合 null |
Response body¶
result_codeでトークン検証結果を確認してください。 JWT検証に失敗した場合 token_validationで詳細エラーを確認してください。エラーの意味は JWT検証エラーコードをご覧ください。
| フィールド名 | 説明 | タイプ | 場所 |
|---|---|---|---|
result_code | 結果コード。 0は検証成功。 レスポンスコード 参考 | Integer | 応答本文 |
result_msg | 結果メッセージ | String | 応答本文 |
token_validation | JWT検証結果 | Object | 応答本文 |
token_validation.result_code | JWT検証結果コード | Integer | token_validation 子 |
token_validation.result_msg | JWT検証結果メッセージ | String | token_validation 子 |
data | リクエストに応じて include_fieldsに指定した情報を含むオブジェクト | Object | 応答本文 |
レスポンスコード¶
検証結果に応じて、以下のコードを返します。
0: 成功2300: 払い戻しユーザーの再決済対象2499:JWT検証に失敗しました。token_validation参考4000: 無効なパラメータ4001: リクエストJSONエラー5000: DBエラー6000: 無効appid6001: IdP トークンエラー7000: 無効なトークン7001: 要求ヘッダーにトークン値がない9999:不明なエラー
Request example¶
基本要求と追加情報を要求する本文の例です。リクエストヘッダには、上記のトークンと ISCRYPTを別途含めてください。
基本リクエスト¶
必須フィールドのみを含む要求本文の例です。
{
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"did": "255764404509548",
"player_id": 10000000000
}
追加情報のリクエスト¶
include_fieldsとして4つの追加情報を要求する本文の例です。
{
"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¶
トークン検証が成功したかどうか、および追加情報の要求による応答の例。
検証成功¶
トークン検証に成功した応答の例です。
{
"result_code": 0,
"result_msg": "SUCCESS",
"token_validation": {
"result_code": 0,
"result_msg": "success"
}
}
JWT検証失敗¶
JWT の有効期限が切れて検証に失敗した応答の例です。
{
"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."
}
}
追加情報を含める¶
include_fieldsとして要求された情報 dataに含まれる応答の例です。