Skip to content

Change the password

Method

ChangeUsernamePasswordAsync

To change the login password of a username account, call ChangeUsernamePasswordAsync(). It is available only for accounts linked with the username login method, and it verifies the user's identity by also sending the current password.

When the password is changed, the Hive Axyl authentication server revokes the login sessions on all devices, including the current device. If the change succeeds, guide the user to log in again with the new password.

Warning

The Hive Axyl SDK does not hash passwords. In the app client, convert the original password the user entered into a 64-character hexadecimal string with SHA256(raw_password) and pass that string. Do not send the plaintext password.

1. Prepare the call parameter values

Convert the current password and the new password into hash strings. The new password must differ from the current password.

using System.Security.Cryptography;
using System.Text;

// Convert the original password into a 64-character SHA256 hexadecimal string.
static string Sha256Hex(string raw)
{
    using var sha256 = SHA256.Create();
    byte[] hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(raw));
    var sb = new StringBuilder(hash.Length * 2);
    foreach (byte b in hash) sb.Append(b.ToString("x2"));
    return sb.ToString();
}

2. Change the password

Call parameters

Field name Type Required Description
request UsernamePasswordChangeRequest Required Password information to change
context ApiCallContext Optional Per-call settings object. If omitted, the default values are used.

UsernamePasswordChangeRequest

Field name Type Required Description
CurrentPassword string Required SHA256(raw_password) value of the current password
NewPassword string Required SHA256(raw_password) value of the new password. It must differ from the current password.

Call example

The return object of ChangeUsernamePasswordAsync(), AuthChangeUsernamePasswordResult, is divided into success, Outcome (feature-specific results), and Failure (the call could not be completed). This method does not throw exceptions and delivers every processing result through the return object, so branch with a switch statement instead of try/catch.

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

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

// rawCurrentPassword and rawNewPassword are the original passwords the user entered.
var result = await auth.ChangeUsernamePasswordAsync(new UsernamePasswordChangeRequest {
    CurrentPassword = Sha256Hex(rawCurrentPassword),
    NewPassword     = Sha256Hex(rawNewPassword),
});

switch (result)
{
    case AuthChangeUsernamePasswordResult.Success:
        // Change complete → guide the user to log in again with the new password.
        Debug.Log("Password change completed");
        break;

    case AuthChangeUsernamePasswordResult.UsernameVerifyFailed:
        // The current password does not match.
        Debug.LogWarning("Ask the user to enter the current password again.");
        break;

    case AuthChangeUsernamePasswordResult.SamePassword:
        // The new password is the same as the current password.
        Debug.LogWarning("Ask the user to enter a different password.");
        break;

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

Response data

No response data is returned on success.

Response status

The return object AuthChangeUsernamePasswordResult branches into one of the following cases.

Response case Description App client handling
Success The password was changed successfully Guide the user to log in again with the new password
UsernameVerifyFailed The current password does not match Guide the user to re-enter the current password
SamePassword The new password is the same as the current password Guide the user to enter a different password
UsernameNotFound The username account cannot be found Check the account status
ProviderNotExist The username login method is not linked to this account Check whether username login is linked
TokenRevokeFailed Revoking the login sessions failed, so the request was not completed Try again later
IpBlocked The access IP is blocked Inform the user of the policy
AppNotFound, TerminateService The app information cannot be found, or the app's service has ended Check the App ID registration status and the service operation status in the console
AppIdMismatch, InvalidGatewayContext The App ID in the request differs from the project of the authentication token, or the authentication context is invalid Check the App ID used for SDK initialization and the session status
UnknownOutcome A new result that this SDK version does not know 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 stored in Failure.Problem.ExternalCode. See Common error handling. Handle according to the common error handling criteria