コンテンツにスキップ

トークン検証

「トークン検証」APIは、アプリクライアントのログイン結果である PlayerInfo のユーザートークン、Player ID、DID(Instance ID)を使用してトークンの有効性を検証します。アプリサーバーからHive認証サーバーを直接呼び出すサーバー間通信方式で動作します。

アプリが冗長ログインを許可していない場合にのみ、検証したトークンを管理したり、アプリ独自のセッションキーを使用したセッション管理機能を実装したりできます。

「トークン検証」APIは、X-Access-Token に使用するJWTに応じて2つの方式をサポートします。

どちらの方法も 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: 無効 appid
  • 6001: 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: 無効 appid
  • 6001: 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
    }
}