Create a guest account

To create a guest account, use ClientId, PKCE, and DeviceKey. If you apply additional security, also use GrantKey.

1. Prepare the call parameters

Prepare the parameters required to create a guest account.

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('/', '_');

DeviceKey

DeviceKey is a device identification value that distinguishes login sessions by device. The Hive Axyl authentication server does not issue or interpret this value, so the app must create and pass it itself.

Server validation conditions

The Hive Axyl authentication server validates only the length and characters of DeviceKey. If you send a value that does not meet the conditions, the account creation request fails. For failure handling, see Common error handling.

Length: 22 to 64 characters
Characters: Only ASCII characters excluding spaces and control characters are allowed; Korean characters and emoji are not allowed
Format: Not validated

Conditions the app must meet

The server does not check whether this value actually corresponds to one device, so the app itself must meet the following conditions.

A different value for each device. A random value such as a UUID is recommended
A value that is saved on the device and reused continuously

When the conditions are not met

If you create a new value for every call, the server recognizes the same device as a different device each time. Conversely, if you put a fixed value in the app code, every device of every user of that app sends the same value. Even a fixed value passes server validation as long as it meets the validation conditions above.

In an app with a fixed value, if one user logs in on two devices, the server treats them as the same device. The device that logs in later overwrites the login session of the earlier device, so the user must log in again every time they switch between devices. Logging out on one device also ends the login on the other device. Because the server returns no error, this symptom surfaces only after user inquiries pile up.

Creation example

The app decides the format. You can use any scheme you want, such as UUID, a hexadecimal string, or base64, and UUID v4 is recommended. The example below creates a 32-character string by removing the hyphens from a UUID v4.

Unity

using System;

// deviceKey: Create it only once on first launch, and save the created value on the device to keep reusing it.
static string NewDeviceKey() => Guid.NewGuid().ToString("N");

Note

Pass the same DeviceKey created here when you log in again with the same guest account later.

2. Create a guest account

CreateGuestAsync

Call CreateGuestAsync() to create a guest account.

Call parameters

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

GuestCreateRequest

Field name	Type	Required	Description
`ClientId`	string	Required	Client ID of the console security key issued per project
`CodeChallenge`	string	Required	PKCE code challenge (SHA256 hash of `codeVerifier`)
`CodeChallengeMethod`	`CodeChallengeMethod`	Required	PKCE method. `S256`
`DeviceKey`	string	Required	Device identification value that distinguishes login sessions by device. 22 to 64 characters
`GrantKey`	string	Optional	The grant key that the app server obtained and passed. Required for apps with additional security turned on. You can send it even when additional security is off, and a sent value is always validated and consumed regardless of the setting. See Apply additional security.

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;
using UnityEngine;

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

var (codeVerifier, codeChallenge) = CreatePkce();
// Create a new value only on first launch. Save the created value on the device and reuse it in later requests.
string deviceKey = NewDeviceKey();

var result = await auth.CreateGuestAsync(new GuestCreateRequest {
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
    // GrantKey: We recommend passing the grant key issued to the app server, in case you turn on additional security.
});

switch (result)
{
    case AuthCreateGuestResult.Success success:
        long   playerId   = success.Data.PlayerId;
        string guestToken = success.Data.GuestToken;
        // Reusing playerId, guestToken, and deviceKey lets you log in with the same guest account.
        break;

    // Handle common failures (network and server errors)
    case AuthCreateGuestResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // Safety net: unhandled results and unknown new results (UnknownOutcome)
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Response data

On success, the result is contained in Data (GuestCreateResponseData) of AuthCreateGuestResult.Success.

Field name	Type	Required	Description
`Data.PlayerId`	long	Required	Player ID that identifies the newly created account
`Data.GuestToken`	string	Required	Guest credential used to log in again
`Data.AuthorizationCode`	string	Required	Authorization code used to issue access tokens and refresh tokens
`Data.CreatedAt`	DateTimeOffset	Required	Creation time (UTC)

Data.PlayerId, Data.GuestToken, DeviceKey, and ClientId are required in the next guest login step.

Note

Data.PlayerId, Data.GuestToken, DeviceKey, and ClientId are also required to log in again with the same account in production. Data.AuthorizationCode is an authorization code used to issue access tokens and refresh tokens. However, this code is not used in the login process. You get a new authorization code required for login later, in the Log in step.

Response example

Unity

// Example of success.Data in the Success branch
// success.Data.PlayerId          = 12345
// success.Data.GuestToken        = "gt_..."
// success.Data.AuthorizationCode = "ac_..."
// success.Data.CreatedAt         = 2026-06-10T00:00:00+00:00   // DateTimeOffset(UTC)

Response status

We recommend handling the response cases of AuthCreateGuestResult with a switch statement.

Response case	Description	App client handling
`Success`	Guest account creation succeeded. `Data` contains `PlayerId`, `GuestToken`, and so on.	Check the account creation result, and then proceed to the login step
`InvalidClientId`	The Client ID is invalid	Check the console security key
`InvalidGrantKey`	The grant key sent in `GrantKey` is invalid or expired	Get a new grant key from the app server and retry. See Apply additional security
`GrantRequiredMissing`	The additional security (grant key) setting is enabled, but `GrantKey` is missing	Check the Apply additional security settings
`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

To log in with the account you created, see Log in.

Note

Creating an account alone does not create a login session. The login session is created in the Log in step.