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 when the app needs its own login UI and direct IdP authentication handling.

Note

To use the custom web login API, app registration and OAuth 2.0 Access Token issuance must be completed in Hive Console.

Overview¶

Use custom web login in the following cases.

When you want to apply an app-specific login UI/UX
When you want to implement a login screen consistent with the existing website design
When you want to process login within your own page without redirecting to the web login page

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

IdP sign-in¶

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

Warning

The custom web login API does not support creating guest (GUEST, idp_index: 0) accounts.

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 account deletion, set it to false.

Request URL¶

Production URL	https://auth.qpyou.cn/v2/game/auth/signinidp
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/signinidp
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

Field name	Description	Type	Required
X-Access-Token	OAuth 2.0 Access Token for app server authentication (See OAuth Token issuance)	String	Y
ISCRYPT	Whether data is encrypted (0 = not encrypted) (always send 0)	Integer	Y

Request body¶

Field name	Description	Type	Required
appid	App ID	String	Y
idp_index	IdP index code (IdP list)	Integer	Y
idp_user_id	Unique IdP user identifier	String	Y
require_token	Whether to request a player token. `true` when using Delete account, otherwise `false`	Boolean	Y

Request example¶

{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","idp_index":3,"idp_user_id":"google_67890","require_token":true}

Response header¶

Field name	Description	Type
Authorization	Session token. Used when calling Delete account API	String

Response body¶

Field name	Description	Type
result_code	Response code Details	Integer
result_msg	Result message	String
token_validation	JWT validation result (JWT validation error)	Object
token_validation.result_code	JWT validation result code	Integer
token_validation.result_msg	JWT validation result message	String
data	Result data	Object
data.player_id	Player ID	Integer
data.idp_index	IdP index	Integer
data.idp_id	IdP name	String
data.idp_user_id	IdP user ID	String

Response code¶

Code value	Description
0	Success
2499	JWT validation failed (see token_validation)
4200	IdP does not exist
5000	Internal server error

IdP linking¶

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

Request URL¶

Production URL	https://auth.qpyou.cn/v2/game/auth/connect
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/connect
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

Field name	Description	Type	Required
X-Access-Token	OAuth 2.0 Access Token for app server authentication (See OAuth Token issuance)	String	Y
ISCRYPT	Whether data is encrypted (0 = not encrypted) (always send 0)	Integer	Y

Request body¶

Field name	Description	Type	Required
appid	App ID	String	Y
idp_index	IdP index code (IdP list)	Integer	Y
idp_user_id	Unique IdP user identifier	String	Y
player_id	Player ID to link	Integer	Y

Request example¶

{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","idp_index":2,"idp_user_id":"fb_12345678","player_id":100000001}

Response body¶

Field name	Description	Type
result_code	Response code Details	Integer
result_msg	Result message	String
token_validation	JWT validation result (JWT validation error)	Object
token_validation.result_code	JWT validation result code	Integer
token_validation.result_msg	JWT validation result message	String
data	Result data	Object
data.player_id	Player ID	Integer
data.idp_index	Linked IdP index	Integer
data.idp_id	Linked IdP name	String
data.idp_user_id	IdP user ID	String

Response code¶

Code value	Description
0	Success
1002	The IdP is already linked to another player
1003	The same IdP type is already linked
2002	Player does not exist
2499	JWT validation failed (see token_validation)
4200	IdP does not exist
5000	Internal server error

IdP unlinking¶

Unlinks an IdP from a player account. You must call this API after signing in with the IdP sign-in API.

Request URL¶

Production URL	https://auth.qpyou.cn/v2/game/auth/disconnect
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/disconnect
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

Field name	Description	Type	Required
X-Access-Token	OAuth 2.0 Access Token for app server authentication (See OAuth Token issuance)	String	Y
ISCRYPT	Whether data is encrypted (0 = not encrypted) (always send 0)	Integer	Y

Request body¶

Field name	Description	Type	Required
appid	App ID	String	Y
idp_index	IdP index code (IdP list)	Integer	Y
idp_user_id	Unique IdP user identifier	String	Y
player_id	Player ID	Integer	Y

Response body¶

Field name	Description	Type
result_code	Response code Details	Integer
result_msg	Result message	String
token_validation	JWT validation result (JWT validation error)	Object
token_validation.result_code	JWT validation result code	Integer
token_validation.result_msg	JWT validation result message	String

Response code¶

Code value	Description
0	Success
2499	JWT validation failed (see token_validation)
4006	Linked IdP information does not exist
4200	IdP does not exist
5000	Internal server error
7000	Invalid token

Delete account¶

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

Set require_token to true when calling the IdP sign-in API.
Store the Authorization value returned in the response header.
Include the stored Authorization value in the request header when calling this API.

Warning

Account deletion cannot be undone. Provide sufficient notice to the user before deletion.

Request URL¶

Production URL	https://auth.qpyou.cn/v2/game/player/delete-project
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/player/delete-project
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

Field name	Description	Type	Required
X-Access-Token	OAuth 2.0 Access Token for app server authentication (See OAuth Token issuance)	String	Y
ISCRYPT	Whether data is encrypted (0 = not encrypted) (always send 0)	Integer	Y
Authorization	Session token received in the response header after calling IdP sign-in with `require_token: true`	String	Y

Request body¶

Field name	Description	Type	Required
appid	App ID	String	Y
player_id	Player ID to delete	Integer	Y
did	Device ID. Fixed to `0`	Integer	Y

Response code¶

Code value	Description
0	Success
2499	JWT validation failed (see token_validation)
5000	Internal server error
7000	Invalid token
7001	No token in header

Note

When JWT validation fails, you can check detailed error information in the token_validation field. For details, see JWT validation error codes.