Log in with a custom account

A custom account is a login method that links an account from an authentication system your app operates itself to a Hive Axyl account. Choose it when you use an authentication method other than the external authentication providers that Hive Axyl officially supports, or when you need to keep using a member system you already operate.

Unlike other login methods, the app client does not send the authentication result directly to the Hive Axyl authentication server. After the app server authenticates the user, it obtains a grant key, which is a pre-authentication key, from the Hive Axyl server and passes it to the app client. The app client logs in with this grant key. Because the user's credentials do not pass through the app client, the risk of exposure is reduced.

The app server and the app client share the work of custom account login.

The app client authenticates the user with the app server or with the authentication system that the app uses.
The app server requests a grant key from the Hive Axyl server with Issue a pre-authorization key. At this time, it also passes the custom authentication provider identifier and the user identifier from that provider.
The app server passes the issued grant key to the app client.
The app client calls LoginCustomProviderAsync() with the grant key.
The Hive Axyl authentication server validates the grant key and returns the linked Player ID and an authorization code for token issuance.

A grant key is valid for only 60 seconds after it is issued and can be used only once. Therefore, the app server must get it issued right when the app client attempts to log in.

For the concept of the grant key and what the app server handles, see Apply additional security.

Note

A new Player ID is issued for a custom account that logs in for the first time. To link a custom account to a Player ID that is already in use, use Link a custom account.

Prepare the call parameters for the custom account login method.

GrantKey

The pre-authentication key that the app server obtained and passed to the app client.

DeviceKey, ClientId, PKCE

Prepare DeviceKey, ClientId, and the PKCE codeChallenge in the same way as for other login methods. For the meaning of each value and how to prepare it, see Values the app client prepares.

Keep the codeVerifier that pairs with codeChallenge in the app, because you use it in the token issuance step.

LoginCustomProviderAsync

Call LoginCustomProviderAsync() to log in with a custom account. The Hive Axyl authentication server validates the grant key, and then processes sign-up if the account is logging in for the first time, or login if the account already exists.

Call parameters

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

CustomLoginRequest

Field name	Type	Required	Description
`GrantKey`	string	Required	Pre-authentication key that the app server obtained and passed on
`DeviceKey`	string	Required	Device identification value. 22 to 64 characters
`ClientId`	string	Required	Client ID of the console security key
`CodeChallenge`	string	Required	PKCE code challenge
`CodeChallengeMethod`	`CodeChallengeMethod`	Required	PKCE method. `S256`

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();

var result = await auth.LoginCustomProviderAsync(new CustomLoginRequest {
    GrantKey            = customLoginGrantKey,
    DeviceKey           = deviceKey,
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
});

switch (result)
{
    case AuthLoginCustomProviderResult.Success success:
        // Login succeeded → issue tokens and activate the session.
        await StartSessionAsync(success.Data.AuthorizationCode, codeVerifier, success.Data.PlayerId);
        break;

    case AuthLoginCustomProviderResult.InvalidGrantKey:
        // The grant key expired or was already used → get a new one from the app server and retry
        break;

    case AuthLoginCustomProviderResult.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;
}

CreatePkce() is a helper defined in Create a guest account. For the definition of StartSessionAsync() and the session activation procedure, see Issue tokens and activate the session.

Response data

On success, Data (LoginResponseData) of AuthLoginCustomProviderResult.Success contains the result. The response data structure is the same as the response data of Log in with an external authentication provider.

Field name	Type	Required	Description
`Data.PlayerId`	long	Required	Logged-in Player ID. If there is no linked account, a new one is issued.
`Data.AuthorizationCode`	string	Required	Authorization code used to issue the access token and refresh token. It expires 180 seconds after it is issued.
`Data.ProviderList`	`IReadOnlyList<ProviderInfo>`	Required	List of login methods linked to this Player ID
`Data.IsBlock`	bool	Required	Whether usage is restricted
`Data.CreatedAt`	DateTimeOffset	Required	Time the account was first created (UTC)

Response example

Unity

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

Response status

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

Response case	Description	App client handling
`Success`	Login succeeded. Issue tokens with `Data.AuthorizationCode`, and then activate the session.	Issue tokens, and then activate the session
`InvalidGrantKey`	The grant key has expired, has already been used, or does not match the request information	Get a new grant key from the app server and retry
`ProviderNotSupported`	Custom account login is not supported	Check the login settings in the console
`ProviderConfigNotFound`	There are no custom account settings in the console	Check the login settings in the console
`InvalidClientId`	The Client ID is incorrect	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 that this SDK version does not know	Log it and handle it conservatively
`Failure`	Common Failure. Missing required parameters or format errors (`invalid_parameter`), missing required fields (`missing_field`), and a missing `X-App-Id` header (`missing_app_id`) also branch here, and the cause is stored in `Failure.Problem.ExternalCode`. See Common error handling.	Handle according to the common error handling criteria

Log in with a custom account

1. Review the custom account login flow

2. Prepare the call parameter values