Skip to content

Link accounts and get linked login methods

Method

LinkProviderAsync

The Player ID is the value that identifies a logged-in user. To link an additional login method to the currently logged-in Player ID, call LinkProviderAsync(). Once linking is complete, whichever linked login method the user logs in with, the user logs in with the same Player ID and keeps using the same play data.

The following policies apply to account linking.

  • Linking is possible only while logged in
  • One login method of each type per Player ID
  • Guest cannot be linked
  • Two different accounts cannot be merged

If a login method of the same type is already linked, the linking request is rejected. To switch to a different account, first remove the existing link with Unlink accounts, and then link the new account. If the account you are trying to link is already linked to another Player ID, an account linking conflict occurs. For how to handle it, see Handle account linking conflicts.

When you link a login method for the first time to an account that started as a guest, the Hive Axyl authentication server invalidates the guest token of that Player ID. The guest token is the credential for re-login that was issued in Create a guest account and stored on the device. After linking, the linked login method becomes the way into that account, so delete the stored guest token when linking succeeds. If you leave it, the next launch attempts a guest login with a value that can no longer be used, and the attempt is rejected with InvalidGuestToken.

Custom accounts are linked with a grant key issued to the app server, so they do not use this method. See Link a custom account.

LinkProviderAsync() requires a user identifier and an authentication result so that the Hive Axyl authentication server can verify that the account to link actually belongs to the user. Therefore, before you call this method, you must first authenticate with the login method to link and obtain these two values.

External authentication provider accounts

For Google, Apple, Google Play Games, Steam, and X accounts, authenticate with the Add-on for each login method or with a web login session to receive ProviderUserId and ProviderToken. For how to authenticate with each login method, see Log in with an external authentication provider.

Username accounts

Put the username entered by the user in ProviderUserId, and put the password, converted with SHA256(raw_password) into a 64-character hexadecimal string, in ProviderToken. The Hive Axyl SDK does not hash passwords, so convert the password yourself in the app client. Do not send plaintext passwords.

When linking a username, the Hive Axyl authentication server handles the request differently depending on the state of the entered username. If the same username does not exist, it creates a new username account with the entered value and links it to the current Player ID. If another Player ID is already using the username, it rejects the request with UsernameAlreadyExists. If the username was created before but is not currently linked to any Player ID, it verifies the password and then links the username to the current Player ID.

Call parameters

Field name Type Required Description
request ProviderLinkRequest Required Information on the login method to link
context ApiCallContext Optional Per-call settings object. If omitted, the default values are used.

ProviderLinkRequest

Field name Type Required Description
ProviderId Provider Required The login method to link. One of Google, SigninApple, GooglePlayGames, Steam, X, and Username. Guest cannot be used; if you specify Guest, Failure is returned, and Failure.Problem.ExternalCode contains invalid_parameter.
ProviderUserId string Required User identifier of the account to link. When linking a username, this is the username string.
ProviderToken string Required Authentication result of the account to link. When linking a username, this is the SHA256(raw_password) value of the password. This is sensitive information, so do not write it to logs.

Call example

AuthLinkProviderResult, the object returned by LinkProviderAsync(), is divided into success, Outcomes (feature-specific results), and Failure (the call could not be completed). This method does not throw exceptions and delivers every processing result through the returned object, so branch with a switch statement instead of try/catch.

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

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

// googleUserId and googleIdToken are values received earlier from the Google login Add-on.
var result = await auth.LinkProviderAsync(new ProviderLinkRequest {
    ProviderId     = Provider.Google,
    ProviderUserId = googleUserId,
    ProviderToken  = googleIdToken,
});

switch (result)
{
    case AuthLinkProviderResult.Success success:
        // Linking complete → update the linking list on the screen.
        Debug.Log($"Linking completed: {success.Data.ProviderId} (PlayerId={success.Data.PlayerId})");
        break;

    case AuthLinkProviderResult.ProviderOwnedByOther:
        // Account already used by another Player ID → move to the conflict handling flow.
        ShowLinkConflictPopup();
        break;

    case AuthLinkProviderResult.ProviderTypeAlreadyExists:
        // A login method of the same type is already linked → guide the user to unlink the existing link.
        Debug.LogWarning("A login method of the same type is already linked.");
        break;

    // Handle common failures (network and server errors)
    case AuthLinkProviderResult.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, Data of AuthLinkProviderResult.Success contains the information of the login method you just linked.

Variable name Type Required Description
Data.PlayerId long Required Player ID to which the login method was linked
Data.ProviderId Provider Required Linked login method
Data.ProviderUserId string Required User identifier of the linked account
Data.ProviderIndex int Required Numeric identifier that represents the linked login method

Response example

// Example of success.Data in the Success branch
// success.Data.PlayerId       = 10000021454
// success.Data.ProviderId     = Provider.Google
// success.Data.ProviderUserId = "104839..."
// success.Data.ProviderIndex  = 2

The returned AuthLinkProviderResult object branches into one of the following cases.

Response case Description App client handling
Success Linking succeeded. Data contains the information of the linked login method. Update the linking list
ProviderTypeAlreadyExists When a login method of the same type is already linked Guide the user to unlink the existing link and try again
ProviderOwnedByOther When the account to link is already linked to another Player ID See Handle account linking conflicts
ProviderAlreadyConnected When the account is already linked to this Player ID Update the screen to the linked state
ProviderTokenError When verification of the login method's authentication result fails Guide the user to authenticate again with that login method
ProviderRequestFailed When a request that the Hive Axyl authentication server sent to the external authentication provider fails Retry or show an error message
InvalidUsernameFormat · InvalidPasswordFormat When the username or password does not meet the format requirements Check the input values and the hash conversion result
UsernameVerifyFailed When you tried to link a username that has no owner, but the password does not match Guide the user to enter the password again
UsernameAlreadyExists When the username is already used by another Player ID Guide the user to enter a different username
IpBlocked When the access IP is blocked Inform the user of the policy
PlayerNotFound When the logged-in player information cannot be found Prompt the user to log in again
AppNotFound · TerminateService When the app information cannot be found or the app's service has been terminated Check the App ID registration status and the service operation status in the console
ProviderConfigNotFound · ProviderClientInfoNotExists When the console has no settings or client information for this login method Check the login settings in the console
AppIdMismatch · InvalidGatewayContext When the App ID of the request differs from the project of the authentication token, or the authentication context is invalid Check the App ID used for SDK initialization and the session state
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 contained in Failure.Problem.ExternalCode. See Common error handling. Handle it according to the common error handling guidelines

Get linked login methods

There is no separate method that retrieves only the list of login methods linked to the current Player ID. Check it with Data.ProviderList, which comes in the login response. For the login response data structure, see Log in with an external authentication provider.

ProviderInfo

Each item in Data.ProviderList has the following values.

Variable name Type Required Description
ProviderUserId string Required User identifier of the linked account
ProviderId Provider Required Linked login method
ProviderIndex int Required Numeric identifier that represents the linked login method

If you link or unlink after login, this list is not sent again. Update the linking list on the screen yourself in the app client: add an item with Data from the LinkProviderAsync() success response, and remove the unlinked item when UnlinkProviderAsync() succeeds.

The list returned by Get supported login methods contains the login methods available in this app, while Data.ProviderList contains the login methods actually linked to this account. The two lists are different.