Steam login Add-on

An Add-on that gets a Steam Web API authentication ticket on Windows and macOS with ISteamUser::GetAuthTicketForWebApi of the Steamworks SDK. When you pass the issued ticket to LoginProviderAsync() of the Auth module, the Hive Axyl authentication server checks the ticket with Steam and logs in with the Steam account.

Module information

Package: com.com2usplatform.hiveaxyl.auth.addon.steam
Interface: ISteamPlugin
Namespace: Hive.Axyl.Auth.Addon.Steam
Registration method: AddSteamAuth()
Supported platforms: Windows, macOS
Minimum requirements: macOS 15+, Unity 6000.0+

Prerequisites

The SDK does not initialize the Steam API. The app must call SteamAPI.Init() once when it starts and call SteamAPI.RunCallbacks() every frame so that Steamworks callbacks are delivered. If you run the app outside the Steam client during development, also prepare the steam_appid.txt file.

If you request a ticket when the Steam API is not initialized or the Steam client is not running, no exception is thrown; the call ends with a Failure whose Code is FailedPrecondition. For how to initialize it, see Initialize Steamworks. For how to check whether the Steamworks SDK is ready to use, see ISteamworksContext.

Registration and retrieval

Register the Add-on in the registration step of HiveBootstrap.Initialize, and then retrieve it with HiveCore.TryResolve<T>().

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Auth.Addon.Steam;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth()
           .AddToken()
           .AddSteamAuth();
});

if (HiveCore.TryResolve<ISteamPlugin>(out var steam))
{
    // Code that runs only in Windows and macOS builds
}

Not registered in the Unity Editor

This Add-on is registered only in players built for Windows or macOS. In the Unity Editor, it is not registered even if the platform matches, so using HiveCore.Resolve<T>() throws RegistrationNotFoundException. Always check with TryResolve<T>() before you use it.

For the package installation and registration procedure, see Install and initialize the module.

Method summary

Asynchronous methods take CancellationToken ct = default as the last parameter. For the calling conventions, see Call context.

GetAuthTicketForWebApiAsync(): Issues a Steam Web API authentication ticket
ReleaseTicket(): Releases an issued ticket back to Steam

Methods

GetAuthTicketForWebApiAsync

Gets a Steam Web API authentication ticket and returns it as a hexadecimal string. It receives a ticket handle from Steam, waits for the issuance result callback, and then encodes the ticket value in hexadecimal.

Even if you call it multiple times concurrently, the SDK processes each call independently. However, if the same ticket request is already in progress, Steam may reject it and the call may end with FailedPrecondition, so call it again after you receive the result.

Unity

Task<SteamServiceGetAuthTicketForWebApiResult> GetAuthTicketForWebApiAsync(GetAuthTicketForWebApiRequest request, CancellationToken ct = default)

Request: GetAuthTicketForWebApiRequest
Response: TicketResponse

Result cases — SteamServiceGetAuthTicketForWebApiResult

Result case	Wire code	Description
`Success`	—	The ticket has been issued. `Data.TicketHex` contains the ticket.
`NotAuthenticated`	`not_authenticated`	The user is not logged in to the Steam client. Prompt the app user to log in to Steam.
`UnknownOutcome`	`UNKNOWN`	A new result unknown to this SDK version.
`Failure`	`FAILURE`	The call could not be completed. Check the cause with the HiveError in `Problem`. If the Steam API is not initialized or the Steam client is not running, `Code` is `FailedPrecondition`. If Steam rejects the request because the same ticket request is already in progress, it is also `FailedPrecondition`, and `ExternalCode` is `k_EResultDuplicateRequest`. If a connection to the Steam servers could not be made, it is `Unavailable`. If the call was canceled with `ct` or the plugin was disposed during the request, it is `Cancelled`.

Exceptions

ArgumentNullException: When request is null
ObjectDisposedException: When it is called after the plugin has been disposed with HiveCore.Shutdown() or Dispose()

Call example

Unity

using Hive.Axyl.Auth.Addon.Steam;
using Hive.Axyl.Core;

var request = new GetAuthTicketForWebApiRequest
{
    Identity = identity,   // The same value as the identity used when the ticket is verified
};

var result = await steam.GetAuthTicketForWebApiAsync(request);

switch (result)
{
    case SteamServiceGetAuthTicketForWebApiResult.Success success:
        string providerToken = success.Data.TicketHex;   // ProviderToken of LoginProviderAsync
        break;

    case SteamServiceGetAuthTicketForWebApiResult.NotAuthenticated:
        // Prompt the user to log in to the Steam client.
        break;

    case SteamServiceGetAuthTicketForWebApiResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // Unhandled results and UnknownOutcome
        break;
}

After you get the ticket, pass TicketHex as ProviderToken and call LoginProviderAsync(). This Add-on does not provide the Steam ID64 to put in ProviderUserId, so the app reads it directly from Steamworks. For the implementation procedure, see Get Steam credentials on Windows and macOS.

ReleaseTicket

Releases an issued ticket back to Steam. Steam limits the number of tickets that can be held at the same time, so if you keep getting tickets without releasing them, later issuance requests may fail.

Call it on the Unity main thread. If you pass an unknown ticket or a ticket that has already been released, it does nothing. The same applies if you call it after the plugin has been disposed.

Unity

void ReleaseTicket(string ticketHex)

Parameter	Type	Required	Description
`ticketHex`	`string`	Required	The `TicketHex` value received in the `Success` result of GetAuthTicketForWebApiAsync().

Release the ticket after you receive the login result

The Hive Axyl authentication server checks the ticket with Steam while it processes LoginProviderAsync(). If you release the ticket before then, Steam considers the ticket invalid and login fails. Call this method after you receive the result, whether login succeeded or failed.

Tickets that have not been released are cleaned up all at once when the plugin is disposed. This is only a safety net for shutdown, so release the ticket with this method every time you log in.

Exceptions

ArgumentNullException: When ticketHex is null

For the implementation procedure, see Release the authentication ticket.

Data types

GetAuthTicketForWebApiRequest

Field	Type	Required	Description
`Identity`	`string`	Required	The identity string passed as is to `GetAuthTicketForWebApi` of Steamworks. You must use the same identity value when you verify the ticket. If it is an empty string, the Steamworks default identity is used.

TicketResponse

Field	Type	Required	Description
`TicketHex`	`string`	Required	The Steam Web API authentication ticket encoded as a lowercase hexadecimal string. Use it as `ProviderToken` in the `LoginProviderAsync()` request. We recommend that you use it only once.