Log in with an external authentication provider

External authentication provider login is a common step for Google account, Apple, Google Play Games, Steam, and X login. The Hive Axyl authentication server verifies the credentials that you got through an Add-on or received from Exchange external authorization codes. If the account is authenticating for the first time, the server processes a sign-up; if the account already exists, it processes a login.

This step does not create a session right away; it returns only an authorization code. Login is complete only after you exchange the authorization code for tokens and register them in the session, so continue through Issue tokens and activate the session.

Prepare the call parameters of the external authentication provider login method.

ProviderUserId, ProviderToken

These are the credentials of the user who logs in. Where you get the values depends on the behavior flow.

Direct Token flow: The response data of the Add-on for each login method
Authorization Code flow: Data.ProviderUserId and Data.ProviderToken in the Exchange external authorization codes response

Which Add-on response fields to use is described in 'Step 2. Log in' of each login method.

DeviceKey, ClientId, PKCE

Every login method prepares DeviceKey, ClientId, and the PKCE codeChallenge in the same way. 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 Issue tokens and activate the session.

LoginProviderAsync

Call LoginProviderAsync() to log in with the external authentication provider's credentials. The Hive Axyl authentication server verifies the credentials and returns the Player ID linked to the account and an authorization code for token issuance.

Call parameters

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

ProviderLoginRequest

Field name	Type	Required	Description
`ProviderId`	`Provider`	Required	The login method to log in with. One of `Google`, `SigninApple`, `GooglePlayGames`, `Steam`, and `X`
`ProviderUserId`	string	Required	User identifier issued by the external authentication provider. For Steam, the Steam ID64
`ProviderToken`	string	Required	Authentication result issued by the external authentication provider. `id_token` for Google accounts and Apple, `access_token` for Google Play Games and X, and for Steam, either the authentication ticket received on Windows or macOS or the entire query string that Steam returned on Android or iOS
`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`

Note

Guest login, username login, and custom account login are not handled by this method. See Log in as a guest, Log in with a username, and Log in with a custom account, respectively.

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

// providerUserId and providerToken are values received from an Add-on or external authorization code exchange,
// and deviceKey is the device identification value that the app stores.
var result = await auth.LoginProviderAsync(new ProviderLoginRequest {
    ProviderId          = Provider.Steam,
    ProviderUserId      = providerUserId,
    ProviderToken       = providerToken,
    DeviceKey           = deviceKey,
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
});

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

    case AuthLoginProviderResult.ProviderTokenError:
        // Credential verification failed → prompt the user to authenticate again with that login method
        break;

    case AuthLoginProviderResult.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, and StartSessionAsync() is defined in Issue tokens and activate the session.

Note

You must implement the login screen UI, where the user selects a login method, yourself in the app client. For how to get the list of login methods to display on the screen, see Compose the login screen.

Response data

On success, the result is in Data (LoginResponseData) of AuthLoginProviderResult.Success.

Field name	Type	Required	Description
`Data.PlayerId`	long	Required	The logged-in Player ID. If no linked account exists, a new Player ID is issued; if the user logs in again with the same external account, the same Player ID is returned.
`Data.AuthorizationCode`	string	Required	Authorization code used to issue the access token and refresh token. It expires 180 seconds after issuance.
`Data.ProviderList`	`IReadOnlyList<ProviderInfo>`	Required	List of login methods linked to this Player ID. If at least one external authentication provider is linked, `Guest` is excluded from the list.
`Data.IsBlock`	bool	Required	Whether usage is restricted
`Data.CreatedAt`	DateTimeOffset	Required	Time the account was first created (UTC)

ProviderInfo

Field name	Type	Required	Description
`ProviderId`	`Provider`	Required	Linked login method
`ProviderUserId`	string	Required	User identifier of the linked login method
`ProviderIndex`	int	Required	Numeric identifier of the login method

If Data.IsBlock is true, the user's usage is restricted. For how to check the restriction reason and period and block entry to the app, see Usage restriction.

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

We recommend handling the response cases of AuthLoginProviderResult 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, then activate the session
`ProviderTokenError`	When credential verification fails	Prompt the user to authenticate again with that login method
`ProviderRequestFailed`	When the Hive Axyl authentication server cannot communicate with the external authentication provider	Retry after a while
`ProviderConfigNotFound`	When the console has no settings for this login method	Check the login settings in the console
`ProviderClientInfoNotExists`	When the console has no client information for this login method	Check the login settings in the console
`InvalidClientId`	When the Client ID is invalid	Check the console security key
`IpBlocked`	When the access IP is blocked	Inform the user of the policy
`AppNotFound`	When the app information cannot be found	Check the app registration status in the console
`TerminateService`	When the app's service has ended	Check the service operation status
`UnknownOutcome`	A new result that this SDK version does not recognize	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 in `Failure.Problem.ExternalCode`. See Common error handling.	Handle according to the common error handling criteria

3. Issue tokens and activate the session

The authorization code in the login response alone does not create a logged-in state. You can call other methods that require authentication only after you exchange the authorization code for an access token and a refresh token and register the tokens in the session.

These two steps are the same for every login method, and they are also the same as for guest login and username login. For the full parameters and response status of each method, see Issue a token and Activate the session.

Pass the authorization code and codeVerifier to ITokenService.IssueTokenAsync() to get an access token and a refresh token.
Pass the issued tokens, the Player ID, and the access token expiration time to ISessionManager.SetSession() to register the session.

The authorization code expires 180 seconds after issuance, so make these calls right after login.

The following example combines the two steps into one helper. The implementation examples for each login method call this helper as StartSessionAsync().

Unity

using System;
using System.Threading.Tasks;
using Hive.Axyl.Auth;
using Hive.Axyl.Core;

// Issue tokens with the authorization code and activate the session.
static async Task StartSessionAsync(string authorizationCode, string codeVerifier, long playerId)
{
    ITokenService   token   = HiveCore.Resolve<ITokenService>();
    ISessionManager session = HiveCore.Resolve<ISessionManager>();

    var issueResult = await token.IssueTokenAsync(new AuthorizationCodeTokenRequest {
        GrantType         = "authorization_code",
        ClientId          = "{clientId}",
        AuthorizationCode = authorizationCode,
        CodeVerifier      = codeVerifier,   // Pairs with the codeChallenge sent in the login call
    });
    if (issueResult is not TokenIssueTokenResult.Success issued)
    {
        // Handle token issuance failure (InvalidGrant, InvalidGrantCodeChallenge, and so on)
        return;
    }

    // The SDK does not set the session automatically at login. Register it yourself.
    session.SetSession(
        issued.Data.AccessToken,
        issued.Data.RefreshToken ?? string.Empty,   // SetSession does not accept null
        playerId,
        DateTimeOffset.UtcNow.ToUnixTimeSeconds() + issued.Data.ExpiresIn);
}

Note

After you activate the session, you can configure the access token to refresh automatically when it expires. For details, see Automatic login.

Log in with an external authentication provider

1. Prepare the call parameter values

ProviderUserId, ProviderToken

DeviceKey, ClientId, PKCE

2. Log in with an external authentication provider

Call parameters

ProviderLoginRequest

Call example

Response data

ProviderInfo

Response example

Response status

3. Issue tokens and activate the session

Next steps