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 username 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);
}

Username login integration example using StartSessionAsync

CreatePkce() and Sha256Hex() are the helpers defined in Log in with a username. inputUsername and rawPassword are the values that the user entered on the login screen. deviceKey is a value that the app obtained in Create a username account and manages.

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

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

var (codeVerifier, codeChallenge) = CreatePkce();

// For the password, hash the user's input at login time with SHA256 and pass the hash.
var result = await auth.LoginUsernameAsync(new UsernameLoginRequest {
    Username            = inputUsername,
    Password            = Sha256Hex(rawPassword),
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
});

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

    case AuthLoginUsernameResult.UsernameVerifyFailed:
        // The username or password does not match → prompt the user to enter them again
        break;

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