Custom web login implementation¶

This guide explains how to implement web login directly using the Hive server API instead of the web login page provided by Hive Platform. Refer to this document if you want to build your own login UI and handle IdP authentication yourself.

Note

To use the custom web login API, app registration and issuance of hive_certification_key must be completed in the Hive Console.

Overview¶

Use custom web login in the following cases.

When you want to apply your own login UI/UX
When you want to implement a login screen that matches your existing website design
When you want to process login within your own page without redirecting to the web login page

API list¶

API endpoint	Description
`POST /game/auth/signinidp`	IdP sign-in
`POST /game/auth/connect`	IdP linking
`POST /game/auth/disconnect`	IdP unlinking
`POST /game/player/delete`	Delete account

Common request headers¶

Header name	Type	Required	Description
Content-Type	String	Y	Fixed to `application/json`
Authorization	String	Y or N	Session token. Required for APIs that require token validation; otherwise optional
ISCRYPT	Integer	Y	Whether encryption is used. Fixed to `0`

Common response headers¶

Header name	Type	Description
Authorization	String	Newly issued session token. Issued only when `require_token: true` is set in the IdP sign-in request
ISCRYPT	Integer	Whether the response is encrypted

Common response format¶

Success response¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": { }
}

Failure response¶

{
    "result_code": 4000,
    "result_msg": "Request has invalid format.",
    "data": null
}

IdP sign-in¶

Creates a new player with IdP information or returns the existing player information if the IdP is already registered. When sign-in succeeds, you can check the PlayerID in data.player_id.

Note

To use the Delete account API, set require_token to true to receive the Authorization value in the response header. If you do not use the account deletion feature, you can set it to false.

Request URL¶

Environment	URL
Production	`https://auth.qpyou.com/game/auth/signinidp`
Sandbox	`https://sandbox-auth.qpyou.com/game/auth/signinidp`
HTTP method	`POST`
Content-Type	`application/json`

Request body¶

Field name	Type	Description	Required
appid	String	Game app ID (`AppID`)	Y
idp_index	Integer	IdP index code. See IdP code definitions	Y
idp_user_id	String	Unique IdP user identifier	Y
hive_certification_key	String	Hive certification key	Y
require_token	Boolean	Whether to request a player token. Set to `true` when using the Delete account API; otherwise set to `false`	Y

Request body example¶

{
    "appid": "com.com2us.example",
    "idp_index": 3,
    "idp_user_id": "google_67890",
    "hive_certification_key": "your_certification_key",
    "require_token": true
}

Response header¶

Field name	Type	Description
Content-Type	String	Response data format (JSON) and character encoding (UTF-8) information
Authorization	String	Session token

Response header example¶

HTTP/1.1 200
Content-Type: application/json; charset=UTF-8
Authorization: abcdf7ebce779429ea878f91d5f1c8
Iscrypt: 0

Response body¶

Field name	Type	Description
result_code	Integer	Result code. `0` indicates success
result_msg	String	Result message
data.player_id	Integer	`PlayerID`
data.idp_index	Integer	IdP index
data.idp_id	String	IdP name
data.idp_user_id	String	IdP user ID

Response body sample (success)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": {
        "player_id": 100000002,
        "idp_index": 3,
        "idp_id": "GOOGLE",
        "idp_user_id": "google_67890"
    }
}

Response body sample (failure)¶

{
    "result_code": 4002,
    "result_msg": "Invalid certfication key"
}

Error codes¶

Code	Description	Notes
4002	Certification key error
4200	IdP does not exist
5000	Database error

IdP linking¶

Links a new IdP to an existing player account. You must call this API after signing in through the IdP sign-in API.

Request URL¶

Environment	URL
Production	`https://auth.qpyou.com/game/auth/connect`
Sandbox	`https://sandbox-auth.qpyou.com/game/auth/connect`
HTTP method	`POST`
Content-Type	`application/json`

Request body¶

Field name	Type	Description	Required
appid	String	Game app ID (`AppID`)	Y
idp_index	Integer	IdP index code. See IdP code definitions	Y
idp_user_id	String	Unique IdP user identifier	Y
player_id	Integer	`PlayerID` to link	Y
hive_certification_key	String	Hive certification key	Y

Request body example¶

{
    "appid": "com.com2us.example",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001,
    "hive_certification_key": "your_certification_key"
}

Response body¶

Field name	Type	Description
result_code	Integer	Result code. `0` indicates success
result_msg	String	Result message
data.player_id	Integer	`PlayerID`
data.idp_index	Integer	Linked IdP index
data.idp_id	String	Linked IdP name
data.idp_user_id	String	IdP user ID

Response body sample (success)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": {
        "player_id": 100000001,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

Response body sample (already linked to another player)¶

{
    "result_code": 1002,
    "result_msg": "Already connected other player",
    "data": {
        "player_id": 100000002,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

Error codes¶

Code	Description	Notes
1002	This IdP is already linked to another player
1003	The same IdP type is already linked
2002	Player does not exist
4002	Certification key error
4200	IdP does not exist
5000	Database error

IdP unlinking¶

Unlinks the IdP linked to the player account. You must call this API after signing in through the IdP sign-in API.

Request URL¶

Environment	URL
Production	`https://auth.qpyou.com/game/auth/disconnect`
Sandbox	`https://sandbox-auth.qpyou.com/game/auth/disconnect`
HTTP method	`POST`
Content-Type	`application/json`

Request body¶

Field name	Type	Description	Required
appid	String	Game app ID (`AppID`)	Y
idp_index	Integer	IdP index code. See IdP code definitions	Y
idp_user_id	String	Unique IdP user identifier	Y
player_id	Integer	`PlayerID`	Y
hive_certification_key	String	Hive certification key	Y

Request body example¶

{
    "appid": "com.com2us.example",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001,
    "hive_certification_key": "your_certification_key"
}

Response body¶

Field name	Type	Description
result_code	Integer	Result code. `0` indicates success
result_msg	String	Result message

Response body sample (success)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS"
}

Response body sample (failure)¶

{
    "result_code": 4002,
    "result_msg": "Invalid certfication key"
}

Error codes¶

Code	Description	Notes
4002	Certification key error
4006	No linked IdP information
4200	IdP does not exist
7000	Invalid token

Delete account¶

Deletes a player account. You must call this API after signing in through the IdP sign-in API.

This API requires token validation, so you must complete the following steps first.

When calling the IdP sign-in API, set require_token to true
Store the Authorization value returned in the response header of the IdP sign-in API
When calling this API, include the Authorization value saved above in the request header

Warning

Account deletion cannot be undone. Provide sufficient guidance to users before deleting an account.

Request URL¶

Environment	URL
Production	`https://auth.qpyou.com/game/player/delete`
Sandbox	`https://sandbox-auth.qpyou.com/game/player/delete`
HTTP method	`POST`
Content-Type	`application/json`

Request header¶

Header name	Type	Description	Required
Authorization	String	Session token returned in the response header after setting `require_token: true` when calling IdP sign-in	Y

Request body¶

Field name	Type	Description	Required
appid	String	Game app ID (`AppID`)	Y
player_id	Integer	`PlayerID` to delete	Y
did	Integer	Device ID. Fixed to `0`	Y
hive_certification_key	String	Hive certification key	Y

Request body example¶

{
    "appid": "com.com2us.example",
    "player_id": 100000001,
    "did": 0,
    "hive_certification_key": "your_certification_key"
}

Response body¶

Field name	Type	Description
result_code	Integer	Result code. `0` indicates success
result_msg	String	Result message

Response body sample (success)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS"
}

Response body sample (failure)¶

{
    "result_code": 7000,
    "result_msg": "Invalid token."
}

Error codes¶

Code	Description	Notes
4002	Certification key error
7000	Invalid token
7001	No token in header

IdP code definitions¶

Default IdPs¶

Code	IDP_ID	Description
0	GUEST	Guest
1	HIVE	Membership account
2	FACEBOOK	Facebook
3	GOOGLE	Google
4	QQ	QQ
5	WEIBO	Weibo
6	VK	VK
7	WECHAT	WeChat
8	APPLE	Apple Game Center
9	SIGNIN_APPLE	Sign in with Apple
10	LINE	LINE
11	TWITTER	Twitter
12	WEVERSE	Weverse
13	NAVER	Naver
14	GOOGLE_PLAY_GAMES	Google Play Games
15	HUAWEI	Huawei
16	FUNTAP	Funtap
18	STEAM	Steam
19	X	X (formerly Twitter)
20	TELEGRAM	Telegram
21	XIAOMI	Xiaomi
22	OPPO	OPPO
23	VIVO	VIVO

Custom IdP¶

Code	IDP_ID	Description
1100	CUSTOM_GAME	Game company-provided IdP