Skip to content

Activate the session

Login is complete when you register, in the session, the access token and refresh token issued in the Issue a token step.

Session activation uses AccessToken, RefreshToken, PlayerId, and ExpiresAtSec.

1. Prepare the call parameters for the session activation method

Prepare the parameters required for session activation.

AccessToken, RefreshToken, PlayerId

ExpiresAtSec

Pass the expiration time of the access token in Unix seconds. Data.ExpiresIn in the Issue a token response is the time remaining, in seconds, from issuance, so add it to the current time to calculate the expiration time. issued is the TokenIssueTokenResult.Success object received in the token issuance step.

using System;

// Convert ExpiresIn (time remaining, in seconds) from the token issuance response to the expiration time (Unix seconds).
long expiresAtSec = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + issued.Data.ExpiresIn;

2. Activate the session

Method

SetSession

Call ISessionManager.SetSession() to register, in the session, the access token and refresh token received from token issuance.

Call parameters

Field name Type Required Description
accessToken string Required Access token used to call methods that require authentication
refreshToken string Required Refresh token used for token refresh
playerId long Required Player ID of the logged-in user
expiresAtSec long Required Access token expiration time (Unix seconds)

Call example

Register the tokens in the session manager. SetSession() does not return a result object.

using Hive.Axyl.Core;

ISessionManager session = HiveCore.Resolve<ISessionManager>();

session.SetSession(
    issued.Data.AccessToken,
    issued.Data.RefreshToken ?? string.Empty,
    playerId,
    expiresAtSec);

Response data

No data is returned on success.

Response example

// SetSession has no return value (void).
session.SetSession(issued.Data.AccessToken, issued.Data.RefreshToken ?? string.Empty, playerId, expiresAtSec);

Response status

SetSession() does not return a result object. After the session is registered, the tokens registered here are used when you call methods that require authentication.

Full flow example

Token issuance is performed with IssueTokenAsync(), and session registration with ISessionManager. You can implement this as a method such as StartSessionAsync() that combines guest login, token issuance, and session registration into one. Separating the authorization code and the tokens is a security procedure to reduce the risk of token exposure.

For the result model and handling principles of the common failures (Failure) that prevent the request from being performed, which IssueTokenAsync() returns, see Common error handling.

Note

After you establish the session, it is convenient to turn on automatic refresh for when tokens expire. For details, see AuthTokenRefresh.Enable in Automatic login.

StartSessionAsync implementation example

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

// Issue tokens using authorizationCode and establish 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 failures (InvalidGrant, InvalidGrantCodeChallenge, and so on)
        return;
    }

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

Guest login integration example using StartSessionAsync

CreatePkce() is the helper defined in Log in as a guest. guestPlayerId, guestToken, and deviceKey are values that the app obtained in Create a guest account and manages.

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

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

var (codeVerifier, codeChallenge) = CreatePkce();

// Use the values that the app manages in the same guest account flow.
var result = await auth.LoginGuestAsync(new GuestLoginRequest {
    GuestPlayerId       = guestPlayerId,
    GuestToken          = guestToken,
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
});

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

    case AuthLoginGuestResult.InvalidGuestToken:
        // The guest token passed is invalid → if a login method has been linked, guide the user to log in with it;
        // if none has ever been linked, guide the user to create a guest account again
        break;

    // Handle common failures (network and server errors)
    case AuthLoginGuestResult.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;
}

Learn more