Skip to content

IAuthService

A service that provides account creation, login, account linking and unlinking, usage restriction retrieval, logout, and account deletion for app users. Login-related methods do not return an access token directly; they return an authorization code (AuthorizationCode). Pass this value to ITokenService.IssueTokenAsync to get an access token and a refresh token.

  • Interface: IAuthService
  • Namespace: Hive.Axyl.Auth
  • Package: com.com2usplatform.hiveaxyl.auth

Registration and retrieval

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

var config = CoreConfig.CreateBuilder("{appId}").Build();

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

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

Method summary

For the meaning of the 'Authentication' column, see Authentication requirement notation.

Guest accounts

Method Authentication Description
CreateGuestAsync Not required Creates a new guest account and receives an authorization code and a guest token.
LoginGuestAsync Not required Logs in again with a saved guest token.

Username accounts

Method Authentication Description
CreateUsernameAsync Not required Creates a new account with a username and password.
LoginUsernameAsync Not required Logs in with a username and password.
ChangeUsernamePasswordAsync Session required Changes the login password of a username account.

External authentication providers

Method Authentication Description
GetProviderListAsync Not required Gets the list of login methods that can be displayed in this app.
ExchangeProviderTokenAsync Not required Exchanges an authorization code issued by an external authentication provider for a user identifier and a token on the server.
LoginProviderAsync Not required Logs in or signs up with an external authentication provider account.
LinkProviderAsync Session required Links an additional login method to the logged-in Player ID.
UnlinkProviderAsync Session required Unlinks a linked login method.

Custom accounts

Method Authentication Description
LoginCustomProviderAsync Not required Completes custom account login or sign-up with a grant key.
LinkCustomProviderAsync Session required Links a custom account with a grant key.

Session and account management

Method Authentication Description
LoginWithAccessTokenAsync Access token required Restores the authentication state with a saved access token and receives a new authorization code.
LogoutPlayerAsync Session required Ends, on the server, the login session of the device that sent the request.
GetBlockStatusAsync Session required Gets the usage restriction status of the current player.
WithdrawPlayerAsync Session required Immediately deletes the player account of the current app.

Common parameters

The last parameter of every method is ApiCallContext? context = null. If you omit it, the default values apply. For details, see Call context.

The request parameter of every method that takes a request body is Required. The method descriptions below show only the request type and omit the parameter table. Check the fields of each request type in Data types.

Methods

CreateGuestAsync

Creates a new guest account and starts a login session. A guest token is issued along with the authorization code in the response, and for later re-login, you use this guest token in LoginGuestAsync.

Task<AuthCreateGuestResult> CreateGuestAsync(GuestCreateRequest request, ApiCallContext? context = null);

Result cases — AuthCreateGuestResult

Result case Wire code Description
Success — Guest account creation succeeded.
InvalidGrantKey invalid_grant_key The grant key is invalid or has expired.
GrantRequiredMissing grant_required_missing This authentication flow requires a grant key, but none was passed.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Create a guest account.

LoginGuestAsync

Logs in to an existing guest account again with a saved guest token. The guest token is not reissued, and the existing value remains valid.

Task<AuthLoginGuestResult> LoginGuestAsync(GuestLoginRequest request, ApiCallContext? context = null);

Result cases — AuthLoginGuestResult

Result case Wire code Description
Success — Guest re-login succeeded.
InvalidGuestToken invalid_guest_token The guest token is invalid.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Log in as a guest.

GetProviderListAsync

Gets the list of login methods that can be displayed in this app. Use it to decide which buttons to show on the login screen.

The server determines the country from the request IP, and the app client cannot specify it. Depending on the country, some login methods may be excluded from the list, and if there are no per-app settings, the default settings apply.

Task<AuthGetProviderListResult> GetProviderListAsync(ApiCallContext? context = null);

Result cases — AuthGetProviderListResult

Result case Wire code Description
Success — Retrieval succeeded.
TerminateService terminate_service The service for this project has been terminated.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Get supported login methods.

ExchangeProviderTokenAsync

Exchanges the authorization code issued by an external authentication provider on the Hive Axyl authentication server to receive ProviderUserId and ProviderToken. Do not change the received values; pass them as is to LoginProviderAsync or LinkProviderAsync.

Because the server authenticates with the provider using the client secret registered in the Hive Console, this method exchanges only authorization codes issued through a web-type client that has a client secret. Authorization codes issued through a public client without a client secret, such as a client created for iOS, macOS, or Android apps in Google Cloud Console or X Developer Portal, cannot be exchanged with this method. In this case, complete the token exchange directly in the app client, and then call LoginProviderAsync.

Task<AuthExchangeProviderTokenResult> ExchangeProviderTokenAsync(ProviderTokenRequest request, ApiCallContext? context = null);

Result cases — AuthExchangeProviderTokenResult

Result case Wire code Description
Success — The exchange succeeded.
ProviderNotSupported provider_not_supported The login method is not supported.
ProviderTokenExchangeNotSupported provider_token_exchange_not_supported The login method does not support server-side authorization code exchange.
ProviderTokenError provider_token_error Verification of the login method's token or authorization code failed.
TerminateService terminate_service The service for this project has been terminated.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
ProviderClientInfoNotExists provider_client_info_not_exists The client information for the login method does not exist.
ProviderRequestFailed provider_request_failed The request sent to the external authentication provider failed.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Exchange external authorization codes.

LoginProviderAsync

Logs in or signs up with an external authentication provider account. If there is no linked account, a new Player ID is issued.

Task<AuthLoginProviderResult> LoginProviderAsync(ProviderLoginRequest request, ApiCallContext? context = null);

Result cases — AuthLoginProviderResult

Result case Wire code Description
Success — Login or sign-up succeeded.
ProviderTokenError provider_token_error Verification of the login method's token or authorization code failed.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
ProviderClientInfoNotExists provider_client_info_not_exists The client information for the login method does not exist.
ProviderRequestFailed provider_request_failed The request sent to the external authentication provider failed.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Log in with an external authentication provider.

LinkProviderAsync

Links an additional login method to the logged-in Player ID.

When you link Username, the flow depends on whether the requested username exists and who owns it. If it does not exist, a new one is created and linked. If another account owns it, the result branches to UsernameAlreadyExists. If it has no owner, it is linked again after password verification. When the first login method is linked, the guest token becomes invalid.

Task<AuthLinkProviderResult> LinkProviderAsync(ProviderLinkRequest request, ApiCallContext? context = null);

Result cases — AuthLinkProviderResult

Result case Wire code Description
Success — Linking succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
InvalidUsernameFormat invalid_username_format The username format is invalid.
InvalidPasswordFormat invalid_password_format The password format is invalid.
ProviderTokenError provider_token_error Verification of the login method's token or authorization code failed.
ProviderRequestFailed provider_request_failed The request sent to the external authentication provider failed.
ProviderClientInfoNotExists provider_client_info_not_exists The client information for the login method does not exist.
UsernameVerifyFailed username_verify_failed The username or password is incorrect.
UsernameAlreadyExists username_already_exists The username already exists.
TerminateService terminate_service The service for this project has been terminated.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
PlayerNotFound player_not_found The player information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
ProviderTypeAlreadyExists provider_type_already_exists A login method of the same type is already linked.
ProviderOwnedByOther provider_owned_by_other The login method is already linked to another player.
ProviderAlreadyConnected provider_already_connected The login method is already linked to this player.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For how the app handles each case, see Link accounts and get linked login methods. For how to handle ProviderOwnedByOther, see Handle account linking conflicts.

UnlinkProviderAsync

Unlinks a linked login method. Guest cannot be unlinked, and a login method cannot be unlinked if no other regular login method remains besides the requested one. Guest and custom accounts are not included in the regular login methods referred to here.

Task<AuthUnlinkProviderResult> UnlinkProviderAsync(ProviderUnlinkRequest request, ApiCallContext? context = null);

Result cases — AuthUnlinkProviderResult

Result case Wire code Description
Success — Unlinking succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
ProviderNotSupported provider_not_supported The login method is not supported.
ProviderNotExist provider_not_exist The login method is not linked.
TerminateService terminate_service The service for this project has been terminated.
GuestUnlinkBlocked guest_unlink_blocked Guest is not a login method that can be unlinked.
LastProviderUnlinkBlocked last_provider_unlink_blocked The last remaining login method cannot be unlinked.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Unlink accounts.

LoginWithAccessTokenAsync

Restores the player's authentication state with a saved access token. It does not issue a new access token but returns an authorization code, so call ITokenService.IssueTokenAsync with the returned authorization code to get tokens issued again.

Because the call must be authenticated with a specific access token instead of the current session, you send the token to verify with ApiCallContext.WithAccessToken().

Task<AuthLoginWithAccessTokenResult> LoginWithAccessTokenAsync(TokenLoginRequest request, ApiCallContext? context = null);

Call example

var result = await auth.LoginWithAccessTokenAsync(
    new TokenLoginRequest
    {
        ClientId            = "{clientId}",
        CodeChallenge       = codeChallenge,
        CodeChallengeMethod = CodeChallengeMethod.S256,
    },
    ApiCallContext.WithAccessToken(storedAccessToken));

Result cases — AuthLoginWithAccessTokenResult

Result case Wire code Description
Success — Restoring the authentication state succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
PlayerNotFound player_not_found The player information could not be found.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Automatic login.

LogoutPlayerAsync

Ends, on the server, the login session of the device that sent the request. Sessions on other devices logged in with the same account are kept. An account with only guest linked cannot log out, because it would lose its means of logging in again.

This method does not clear the in-memory session of the app client or the tokens stored on the device. Access tokens that have already been issued remain valid until they expire, so if the result is Success, clean up the session and tokens that the app keeps yourself.

Task<AuthLogoutPlayerResult> LogoutPlayerAsync(ApiCallContext? context = null);

Result cases — AuthLogoutPlayerResult

Result case Wire code Description
Success — Logout succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
TerminateService terminate_service The service for this project has been terminated.
AppNotFound app_not_found The app information could not be found.
PlayerNotFound player_not_found The player information could not be found.
GuestSignoutBlocked guest_signout_blocked An account with only guest linked cannot log out.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For when to delete the saved credentials, see Preserve stored credentials. For the implementation procedure, see Log out.

CreateUsernameAsync

Creates a new account with a username and password. You cannot create a username that already exists in the same app.

Task<AuthCreateUsernameResult> CreateUsernameAsync(UsernameCreateRequest request, ApiCallContext? context = null);

Result cases — AuthCreateUsernameResult

Result case Wire code Description
Success — Account creation succeeded.
InvalidGrantKey invalid_grant_key The grant key is invalid or has expired.
GrantRequiredMissing grant_required_missing This authentication flow requires a grant key, but none was passed.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
UsernameAlreadyExists username_already_exists The username already exists.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Create a username account.

LoginUsernameAsync

Logs in with a username and password.

After password verification passes, if a player is linked to those credentials, it logs in as that player. If no player is linked, such as when the user logs in again after unlinking, a new Player ID is issued in the same way as external authentication provider login, and in this case IsBlock in the response is always false. To link the username to an existing account again, use LinkProviderAsync.

Task<AuthLoginUsernameResult> LoginUsernameAsync(UsernameLoginRequest request, ApiCallContext? context = null);

Result cases — AuthLoginUsernameResult

Result case Wire code Description
Success — Login succeeded.
UsernameVerifyFailed username_verify_failed The username or password is incorrect.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Log in with a username.

ChangeUsernamePasswordAsync

Changes the login password of a username account. Only players who have a username linked can use it, regardless of how the username was linked. The new password must differ from the current password.

When the password is changed, the login sessions on all devices, including the current device, are revoked. If the change succeeds, prompt the user to log in again with the new password.

Task<AuthChangeUsernamePasswordResult> ChangeUsernamePasswordAsync(UsernamePasswordChangeRequest request, ApiCallContext? context = null);

Result cases — AuthChangeUsernamePasswordResult

Result case Wire code Description
Success — The password change succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
SamePassword same_password The new password is the same as the current password.
UsernameVerifyFailed username_verify_failed The username or password is incorrect.
TerminateService terminate_service The service for this project has been terminated.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
ProviderNotExist provider_not_exist The login method is not linked.
UsernameNotFound username_not_found The username does not exist.
TokenRevokeFailed token_revoke_failed Revoking the player's tokens failed. You must try again.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Change the password.

LoginCustomProviderAsync

Completes custom account login or sign-up with a grant key and gets an authorization code. The App ID used to issue the grant key must be the same as the App ID of the request.

Task<AuthLoginCustomProviderResult> LoginCustomProviderAsync(CustomLoginRequest request, ApiCallContext? context = null);

Result cases — AuthLoginCustomProviderResult

Result case Wire code Description
Success — Login or sign-up succeeded.
InvalidGrantKey invalid_grant_key The grant key is invalid or has expired.
ProviderNotSupported provider_not_supported The login method is not supported.
TerminateService terminate_service The service for this project has been terminated.
InvalidClientId invalid_client_id The client identifier is not registered or does not belong to this project.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Custom account login.

LinkCustomProviderAsync

Links a custom account to the currently logged-in player with a grant key. The App ID and Player ID used to issue the grant key must be the same as those of the request. Only custom accounts can be linked; regular login methods and guest are blocked.

Task<AuthLinkCustomProviderResult> LinkCustomProviderAsync(CustomLinkRequest request, ApiCallContext? context = null);

Result cases — AuthLinkCustomProviderResult

Result case Wire code Description
Success — Linking succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
InvalidGrantKey invalid_grant_key The grant key is invalid or has expired.
PlayerIdDoesNotMatch player_id_does_not_match The Player ID does not match the one used to issue the grant key.
ProviderNotSupported provider_not_supported The login method is not supported.
ProviderTypeAlreadyExists provider_type_already_exists A login method of the same type is already linked.
ProviderOwnedByOther provider_owned_by_other The login method is already linked to another player.
ProviderAlreadyConnected provider_already_connected The login method is already linked to this player.
TerminateService terminate_service The service for this project has been terminated.
IpBlocked ip_blocked Access from this IP address has been restricted.
AppNotFound app_not_found The app information could not be found.
PlayerNotFound player_not_found The player information could not be found.
ProviderConfigNotFound provider_config_not_found No login method is configured for this app.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Link a custom account.

GetBlockStatusAsync

Gets the usage restriction status of the current player. A usage restriction is returned as business data, not as an error, so the result branches to Success even if the player is sanctioned.

The sanction notice message is localized in the language of the Accept-Language header. If the message for that language is empty, or if the request asks for a language that the app does not support, the message is returned in the app's default language. Specify the request language with SetLanguage.

Task<AuthGetBlockStatusResult> GetBlockStatusAsync(ApiCallContext? context = null);

Result cases — AuthGetBlockStatusResult

Result case Wire code Description
Success — Retrieval succeeded. Check whether the player is sanctioned with Data.IsBlocked.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
TerminateService terminate_service The service for this project has been terminated.
AppNotFound app_not_found The app information could not be found.
BlockTypeNotFound block_type_not_found The reference information for the restriction type could not be found.
BlockTypeContentNotFound block_type_content_not_found The restriction type exists, but the notice message for the default language could not be found.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Usage restriction.

WithdrawPlayerAsync

Immediately deletes the player account that belongs to the current app, and a deleted account cannot be recovered. All login method links and the guest token are deleted, and if there is a username account, the username and password credentials are deleted as well. Usage restriction data remains. Even if the user logs in again with the same login method after the deletion, the previous account is not restored, and a new Player ID is issued.

Before it deletes the account, it revokes the login sessions on all devices. If revoking the sessions fails, it does not delete the account and returns TokenRevokeFailed, so try again. If the session has already ended, log in again and then try.

Task<AuthWithdrawPlayerResult> WithdrawPlayerAsync(ApiCallContext? context = null);

Result cases — AuthWithdrawPlayerResult

Result case Wire code Description
Success — Account deletion succeeded.
AppIdMismatch app_id_mismatch The app in the X-App-Id header does not belong to the same project as the authentication token.
InvalidGatewayContext invalid_gateway_context The gateway authentication context is missing or invalid.
TerminateService terminate_service The service for this project has been terminated.
AppNotFound app_not_found The app information could not be found.
PlayerNotFound player_not_found The player information could not be found.
TokenRevokeFailed token_revoke_failed Revoking the login sessions failed, so the account was not deleted. Try again.
UnknownOutcome UNKNOWN A new result unknown to this SDK version.
Failure FAILURE The call could not be completed. Common Failure codes also branch into this case.

For the implementation procedure, see Delete an account.

Data types

Fields shared by multiple request types have the same meaning.

  • ClientId: The PKCE client identifier that the Hive Console issues for each project. For how to check it, see Client ID.
  • CodeChallenge: The PKCE code challenge. When you issue tokens, you submit the original of this value as CodeVerifier.
  • CodeChallengeMethod: The PKCE transformation method. Fixed to S256
  • DeviceKey: A device identifier that distinguishes login sessions by device. Create it as a different random value for each device, save it, and reuse it. For the conditions and a creation example, see deviceKey.
  • Username: A username identifier of 3 to 20 characters that includes at least one English letter. Only English letters, numbers, ., _, and - can be used, and the regular expression is ^(?=.*[A-Za-z])[A-Za-z0-9._-]{3,20}$.
  • Password, CurrentPassword, NewPassword: The password converted with SHA256(original password) in the app client. You must not send plaintext, and the conversion result must be in the ^[0-9a-f]{64}$ format, which is 64 lowercase hexadecimal characters.
  • Meta: Additional information that the server sent along as the raw, unprocessed JSON string

BlockDetail

Detailed usage restriction information.

Field Type Required Description
Code int Required The restriction type code in the range 100-999. It is the same value as the code registered in Restriction types in the Hive Console.
Name string Required The localized restriction type name.
Message string Required The localized notice message to show to the user.
StartAt DateTimeOffset Required The start time of the usage restriction. It is in UTC.
EndAt DateTimeOffset? Optional The end time of the usage restriction. It is in UTC, and it is null for a permanent restriction.

BlockStatusResponseData

Field Type Required Description
IsBlocked bool Required Whether the player is subject to a usage restriction.
Block BlockDetail? Optional The usage restriction details. If IsBlocked is false, it is null.
Meta string? Optional Additional information that the server sent along.

CustomLinkRequest

Field Type Required Description
GrantKey string Required The pre-authorization key issued with authType=CUSTOM_LINK. It is valid for 60 seconds and is single-use.

CustomLoginRequest

Field Type Required Description
DeviceKey string Required The device identifier.
GrantKey string Required The pre-authorization key issued with authType=CUSTOM_LOGIN. It is valid for 60 seconds and is single-use.
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.

GuestCreateRequest

Field Type Required Description
GrantKey string? Optional The pre-authorization key that the app server obtained and passed on. It is valid for 60 seconds and is single-use. If you turned on additional security in the Hive Console, you must send it. You can send it even when additional security is off, and the value you send is always verified and consumed regardless of the setting. We recommend that you always send it so that requests are not rejected the moment you turn on additional security.
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.
DeviceKey string Required The device identifier.

GuestCreateResponseData

Field Type Required Description
PlayerId long Required The created Player ID.
CreatedAt DateTimeOffset Required The account creation time.
AuthorizationCode string Required The authorization code to use for token issuance. It is valid for 180 seconds.
GuestToken string Required A 32-character alphanumeric token to use for guest re-login. Store it securely on the device.
Meta string? Optional Additional information that the server sent along.

GuestLoginRequest

Field Type Required Description
GuestPlayerId long Required The Player ID issued when the guest account was created.
GuestToken string Required The guest token issued earlier.
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.
DeviceKey string Required The device identifier.

LoginResponseData

The response that login-related methods return in common.

Field Type Required Description
PlayerId long Required The logged-in Player ID.
CreatedAt DateTimeOffset Required The account creation time.
AuthorizationCode string Required The authorization code to use for token issuance. It is valid for 180 seconds.
ProviderList IReadOnlyList<ProviderInfo> Required The list of login methods linked to this account. If even one login method other than guest is linked, Guest is excluded from the list. Guest is included only for a pure guest that has no other login method at all.
IsBlock bool Required Whether the player is subject to a usage restriction. Even if it is true, login succeeds, so do not treat it as a failure; use it as a signal to display a usage restriction notice. Get detailed information such as the reason and period with GetBlockStatusAsync.
Meta string? Optional Additional information that the server sent along.

ProviderInfo

Information about a login method linked to the player.

Field Type Required Description
ProviderUserId string Required The user identifier of the linked account.
ProviderId Provider Required The linked login method.
ProviderIndex int Required An identifier that represents the login method as a number.

ProviderItem

An available login method item.

Field Type Required Description
ProviderIndex int Required An identifier that represents the login method as a number.
ProviderId Provider Required The login method identifier.

ProviderLinkRequest

Field Type Required Description
ProviderId Provider Required The login method to link. Only Google, SigninApple, GooglePlayGames, Steam, X, and Username are allowed. If you enter a value that is not allowed, such as Guest, the result branches to a Failure whose Problem.ExternalCode is invalid_parameter.
ProviderUserId string Required The user identifier of the login method. For Username, it is a username string in the same format as the shared field Username. If the username already exists, it is linked; if not, a new one is created and linked. If the format is violated, the result branches to InvalidUsernameFormat.
ProviderToken string Required The authentication result token of the login method. For Username, it is a SHA256(original password) value in the same format as the shared field Password. If the username already exists, the password is verified; if not, it is set as the password of the new account. If the format is violated, the result branches to InvalidPasswordFormat.

ProviderLinkResponseData

Field Type Required Description
PlayerId long Required The Player ID to which the login method was linked.
ProviderUserId string Required The user identifier of the linked account.
ProviderIndex int Required An identifier that represents the login method as a number.
ProviderId Provider Required The linked login method.
Meta string? Optional Additional information that the server sent along.

ProviderListResponseData

Field Type Required Description
ProviderList IReadOnlyList<ProviderItem> Required The list of login methods available in this app. It is the result after the app settings and country conditions are applied.
Meta string? Optional Additional information that the server sent along.

ProviderLoginRequest

Field Type Required Description
DeviceKey string Required The device identifier.
ProviderId Provider Required The login method to log in with. Only Google, SigninApple, GooglePlayGames, Steam, and X are allowed. Guest and Username are not allowed; for username login, use LoginUsernameAsync.
ProviderUserId string Required The user identifier of the login method. For Steam, it is the SteamID64, and for web login on iOS and Android, it is the last path value of openid.claimed_id.
ProviderToken string Required The token or authentication result of the login method used for verification. For the value to enter for each login method, see the list below.
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.

The value you put in ProviderToken differs by login method. If you exchanged an authorization code with ExchangeProviderTokenAsync, put the ProviderToken from the response as is.

  • Google, SigninApple: id_token in JWT format
  • GooglePlayGames, X: access_token
  • Steam on Windows and macOS: The hexadecimal string of the session ticket received with GetAuthTicketForWebApiAsync()
  • Steam on iOS and Android: The entire query string that Steam returned to the return_to address

On iOS and Android, send the query string that Steam returned exactly as you received it. If you reassemble or re-encode the openid. parameters, openid.sig signature verification fails.

ProviderTokenRequest

Field Type Required Description
ProviderId Provider Required A login method that supports authorization code exchange. Only Google, SigninApple, GooglePlayGames, and X are allowed. If the value does not support exchange, the result branches to ProviderTokenExchangeNotSupported; if the value is not defined, it branches to ProviderNotSupported.
ProviderCode string Required The authorization code issued by the external authentication provider.
RedirectUri string? Optional The redirect URI to use for the code exchange. It is required for Google, GooglePlayGames, and X. For SigninApple, it is required only when you exchange an authorization code received through web login that uses a Service ID; if the authorization code was received through the native SDK, leave it empty. It must not differ by even a single character from the value used in the authorization request; if it differs, the external authentication provider rejects the exchange. If you appended ?relayTo=... to the redirect URI of the authorization request to go through the Hive Axyl relay URL, send the string as is, including that query.
CodeVerifier string? Optional The PKCE code verifier. It is required for X. For Google, send it only if you used PKCE code_challenge in the authorization request.

ProviderTokenResponseData

Field Type Required Description
ProviderUserId string Required The user identifier confirmed through the exchange.
ProviderToken string Required The token received through the exchange. Pass it as is to the login or linking request.
ProviderId Provider Required The login method whose authorization code was exchanged.
Meta string? Optional Additional information that the server sent along.

ProviderUnlinkRequest

Field Type Required Description
ProviderId Provider Required The login method to unlink. Guest cannot be unlinked. If you enter Guest, the result branches to GuestUnlinkBlocked; if you enter a value that is not defined, it branches to ProviderNotSupported.

TokenLoginRequest

Field Type Required Description
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.

UsernameCreateRequest

Field Type Required Description
GrantKey string? Optional The pre-authorization key that the app server obtained and passed on. It is valid for 60 seconds and is single-use. If you turned on additional security in the Hive Console, you must send it. You can send it even when additional security is off, and the value you send is always verified and consumed regardless of the setting. We recommend that you always send it so that requests are not rejected the moment you turn on additional security.
DeviceKey string Required The device identifier.
Username string Required The username identifier.
Password string Required The password. Convert it with SHA256(original password) in the app client before you send it; you must not send plaintext.
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.

UsernameCreateResponseData

Field Type Required Description
PlayerId long Required The created Player ID.
CreatedAt DateTimeOffset Required The account creation time.
AuthorizationCode string Required The authorization code to use for token issuance. It is valid for 180 seconds.
Meta string? Optional Additional information that the server sent along.

UsernameLoginRequest

Field Type Required Description
DeviceKey string Required The device identifier.
Username string Required The username identifier.
Password string Required The password. Convert it with SHA256(original password) in the app client before you send it; you must not send plaintext.
ClientId string Required The PKCE client identifier.
CodeChallenge string Required The PKCE code challenge.
CodeChallengeMethod CodeChallengeMethod Required Fixed to S256.

UsernamePasswordChangeRequest

Field Type Required Description
CurrentPassword string Required The current password. Convert it with SHA256(original password) in the app client before you send it; you must not send plaintext.
NewPassword string Required The new password. Convert it with SHA256(original password) in the app client before you send it, and it must differ from the current password. If it is the same, the result branches to SamePassword.

VoidResponseData

The response of methods that have no data to return.

Field Type Required Description
Meta string? Optional Additional information that the server sent along.

Enums

Enter the C# member name in app code. The wire value is the string exchanged with the server.

CodeChallengeMethod

The PKCE transformation method. Only S256 of RFC 7636 is supported.

C# member Wire value Description
Unspecified CODE_CHALLENGE_METHOD_UNSPECIFIED The default value when no value is specified. Do not use it in requests.
S256 S256 SHA-256-based transformation. Always use this value in requests.

Provider

The login method identifier.

C# member Wire value Description
Unspecified PROVIDER_UNSPECIFIED The default value when no value is specified. Do not use it in requests.
Guest GUEST Guest account.
Google GOOGLE Google account.
SigninApple SIGNIN_APPLE Sign in with Apple.
GooglePlayGames GOOGLE_PLAY_GAMES Google Play Games.
Steam STEAM Steam account.
X X X (Twitter) account.
Username USERNAME Username account.
CustomProvider CUSTOM_PROVIDER Custom account.