Log in as a guest

Log in with a guest account.

To log in with a guest account, use GuestPlayerId, GuestToken, DeviceKey, ClientId, and PKCE.

1. Prepare the call parameters

Prepare the parameters required for guest login.

GuestPlayerId, GuestToken, DeviceKey

Use GuestPlayerId, GuestToken, and DeviceKey, which are the input or response values from guest account creation. Because DeviceKey goes through the same length and character validation in login requests as well, pass, as is, the value that meets the conditions in DeviceKey.

Note

With the com.com2usplatform.hiveaxyl.storage module, you can save the values above on the user's device and load them for use later. See Automatic login.

ClientId

This is the Client ID that the Hive Console issues per project. All App IDs in the same project use the same value. Check the value in Get the security key.

PKCE: codeChallenge and codeVerifier

PKCE (codeVerifier and codeChallenge) is a pair of one-time values that protects the issued authorization code from being misused even if it is intercepted in transit. The app must generate them itself.

Unity

using System;
using System.Security.Cryptography;
using System.Text;

// PKCE(RFC 7636): generate codeVerifier + codeChallenge = BASE64URL(SHA256(codeVerifier))
static (string verifier, string challenge) CreatePkce()
{
    var bytes = new byte[32];
    using (var rng = RandomNumberGenerator.Create()) rng.GetBytes(bytes);
    string verifier = Base64Url(bytes);
    using var sha = SHA256.Create();
    string challenge = Base64Url(sha.ComputeHash(Encoding.ASCII.GetBytes(verifier)));
    return (verifier, challenge);
}
static string Base64Url(byte[] b) =>
    Convert.ToBase64String(b).TrimEnd('=').Replace('+', '-').Replace('/', '_');

2. Log in as a guest

LoginGuestAsync

Call LoginGuestAsync() to log in with a guest account.

Call parameters

Field name	Type	Required	Description
request	GuestLoginRequest	Required	Guest login request
context	ApiCallContext	Optional	Per-call settings object. If omitted, the default values are used.

GuestLoginRequest

Field name	Type	Required	Description
GuestPlayerId	long	Required	Player ID received at account creation
GuestToken	string	Required	Guest token received at account creation
ClientId	string	Required	Client ID of the console security key issued per project
CodeChallenge	string	Required	PKCE code challenge
CodeChallengeMethod	CodeChallengeMethod	Required	PKCE method. S256
DeviceKey	string	Required	Device identification value that distinguishes login sessions by device. 22 to 64 characters

Call example

For the result model and handling principles of common failures (Failure) that prevent the request from being performed, see Common error handling.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;

IAuthService auth = HiveCore.Resolve<IAuthService>();

var (codeVerifier, codeChallenge) = CreatePkce();

// Returns an AuthLoginGuestResult object
var result = await auth.LoginGuestAsync(new GuestLoginRequest {
    GuestPlayerId       = guestPlayerId,
    GuestToken          = guestToken,
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
});

Note

In production, you must implement the UI for users to select a login method directly in the app client.

Response data

On success, the login result is contained in Data (LoginResponseData) of AuthLoginGuestResult.Success.

Field name	Type	Required	Description
Data.PlayerId	long	Required	Player ID
Data.AuthorizationCode	string	Required	Authorization code used to issue access tokens and refresh tokens (used in Issue a token)
Data.ProviderList	IReadOnlyList<ProviderInfo>	Required	List of authentication providers linked to this account
Data.IsBlock	bool	Required	Whether usage is restricted
Data.CreatedAt	DateTimeOffset	Required	Account creation time (UTC)

Response example

Unity

// Example of success.Data in the Success branch
// success.Data.PlayerId          = 12345
// success.Data.AuthorizationCode = "ac_..."   // Used for token issuance
// success.Data.IsBlock           = false

Response status

We recommend handling the response cases of AuthLoginGuestResult with a switch statement. For an example of the branching code, see the combined example in Activate the session.

Response case	Description	App client handling
Success	Login succeeded. Use Data.AuthorizationCode to issue tokens, and then start the session.	Issue tokens, and then start the session
InvalidGuestToken	The guest token you passed is invalid. When another login method is linked to the account for the first time, the guest token becomes invalid.	Guide the user to log in with the linked login method. If no login method has ever been linked, guide the user to create a guest account again
InvalidClientId	The Client ID is invalid	Check the console security key
IpBlocked	The access IP is blocked	Inform the user of the policy
AppNotFound	The app information cannot be found	Check the app registration status in the console
TerminateService	The app's service has ended	Check the service operation status
UnknownOutcome	A new result unknown to this SDK version	Log it and handle it conservatively
Failure	Common Failure. Missing or malformed required parameters (invalid_parameter), missing required fields (missing_field), and a missing X-App-Id header (missing_app_id) also fall into this case. The cause is contained in Failure.Problem.ExternalCode. See Common error handling.	Handle according to the common error handling criteria

Next steps

• Issue a token