Log in with a username

Log in with a username account.

To log in with a username account, use Username, Password, DeviceKey, ClientId, and PKCE.

1. Prepare the call parameters

Prepare the parameters required for username login.

Username, DeviceKey

Use the Username that the user enters at login and the DeviceKey that the app saved on this device. 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.

Password

For Password, pass the 64-digit hexadecimal string produced by hashing the currently entered password with SHA256. This value must match the password hash sent when the username account was created. The app must generate it itself.

Unity

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

// Do not send the password in plain text; convert it to the hexadecimal string of SHA256(raw) and pass that.
static string Sha256Hex(string raw)
{
    using var sha = SHA256.Create();
    byte[] hash = sha.ComputeHash(Encoding.UTF8.GetBytes(raw));
    var sb = new StringBuilder(hash.Length * 2);
    foreach (byte b in hash) sb.Append(b.ToString("x2"));
    return sb.ToString();
}

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 with a username

LoginUsernameAsync

Call LoginUsernameAsync() to log in with a username account. Use the username and password that the user enters at login, and have the app hash the password with SHA256 before passing it.

Call parameters

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

UsernameLoginRequest

Field name	Type	Required	Description
Username	string	Required	Username entered by the user
Password	string	Required	SHA256 hash of the password that the user entered at login (no plain text). It must be the same as the value sent 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();

// For the password, hash the user's input at login time with SHA256 and pass the hash.
// For DeviceKey, pass the value that the app saved on this device.
// Returns an AuthLoginUsernameResult object
var result = await auth.LoginUsernameAsync(new UsernameLoginRequest {
    Username            = inputUsername,
    Password            = Sha256Hex(rawPassword),
    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 AuthLoginUsernameResult.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          = 1024
// success.Data.AuthorizationCode = "ac_..."   // Used for token issuance
// success.Data.IsBlock           = false

Response status

We recommend handling the response cases of AuthLoginUsernameResult 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
UsernameVerifyFailed	The username or password does not match	Prompt the user to enter them again
InvalidClientId	The Client ID is invalid	Check the console security key
IpBlocked	The access IP is blocked	Inform the user of the policy
ProviderConfigNotFound	No login method (provider configuration) is set for the app	Check the console login settings
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