Account and authentication API

This page describes the Hive Axyl Server APIs that the app server calls directly in 'Account and authentication'. It covers the API that issues a grant key, with which the app server approves account creation, custom account login, and custom account linking in advance, and the API that changes the password of a username account.

Issue a pre-authorization key

POST /auth/v1/grant

The app server gets a grant key that approves an authentication action in advance on behalf of the app client. The app server calls this API after it determines with its own policy that the request is legitimate. When the app server passes the issued value to the app client, the app client includes that value in its account creation, custom account login, or custom account linking request.

A grant key is a single-use value that is valid for only 60 seconds after issuance. Once it is used in an actual authentication request, it is consumed immediately and cannot be used again. Therefore, get it right before the actual request rather than at the point where you wait for user input.

Before calling the API

Caller: app server
Base URL: https://core-api.hiveaxyl.com
Authentication: Authorization: Bearer {access-token}

Warning

Put the token for the app server that you received from Issue a token in the authentication header. The issued grant key is sensitive information that approves an authentication action, so do not leave it in logs or error messages, and use encrypted communication such as HTTPS when you pass it to the app client.

Call parameters

Name	Location	Type	Required	Description
`X-App-Id`	`header`	`string`	`true`	The App ID registered in the Hive Console. If the header is not sent, the response is `missing_field`; if the value is empty, the response is `missing_app_id`.
body	body	`GrantRequest`	`true`	Request body that contains information about the authentication action to approve.

Request body GrantRequest

Field	Type	Required	Description
`authType`	`string`	`true`	Type of the authentication action to approve. One of `GUEST_CREATE`, `USERNAME_CREATE`, `CUSTOM_LOGIN`, and `CUSTOM_LINK`.
`providerId`	`string`	Conditional	Identifier of the custom login method. If `authType` is `CUSTOM_LOGIN` or `CUSTOM_LINK`, send `CUSTOM_PROVIDER`.
`providerUserId`	`string`	Conditional	User identifier issued by the custom login method. Required if `authType` is `CUSTOM_LOGIN` or `CUSTOM_LINK`, and 1 to 255 characters long.
`targetPlayerId`	`integer`	Conditional	Player ID of the target account to link the custom account to. Required if `authType` is `CUSTOM_LINK`.

The fields you must send together for each authType and where the grant key is used are as follows.

`authType`	Approval target	Fields sent together	Where the grant key is used
`GUEST_CREATE`	Guest account creation	None	Create a guest account
`USERNAME_CREATE`	Username account creation	None	Create a username account
`CUSTOM_LOGIN`	Custom account login	`providerId`, `providerUserId`	Log in with a custom account
`CUSTOM_LINK`	Custom account linking	`providerId`, `providerUserId`, `targetPlayerId`	Link a custom account

For the cases in which creating guest and username accounts requires a grant key, see Apply additional security.

Call example

curl

curl -X POST 'https://core-api.hiveaxyl.com/auth/v1/grant' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Id: {app-id}' \
  -d '{
    "authType": "GUEST_CREATE"
  }'

When you link a custom account, send the request as follows.

curl

curl -X POST 'https://core-api.hiveaxyl.com/auth/v1/grant' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Id: {app-id}' \
  -d '{
    "authType": "CUSTOM_LINK",
    "providerId": "CUSTOM_PROVIDER",
    "providerUserId": "{custom-provider-user-id}",
    "targetPlayerId": 20000000234
  }'

Response

For the common data and meta, the error body, and the product common error codes, see Account and authentication responses and errors. This section describes the objects this API actually returns and the handling specific to this API.

Success response data object

Field	Type	Description
`data.grantKey`	`string`	The issued grant key. Pass it to the app client to use in the authentication request.
`data.createdAt`	`string`	Issuance time. In ISO 8601 UTC format; the grant key is valid for only 60 seconds from this time.

Response example

200 OK400 Bad Request

{
  "data": {
    "grantKey": "{grant-key}",
    "createdAt": "2026-04-01T09:00:00Z"
  },
  "meta": null
}

{
  "type": "/errors/auth/provider-config-not-found",
  "title": "Provider Config Not Found",
  "status": 400,
  "detail": "No provider configuration exists for this app.",
  "instance": "/auth/v1/grant",
  "code": "provider_config_not_found",
  "outcome": null
}

Notes for each API

A grant key expires 60 seconds after its issuance time. Do not have the app server create multiple grant keys in advance or cache them. Issue one at a time when the app client requests authentication, and pass it to the app client.

Response status

Status	Content type	Meaning	Response header	Response body or handling
`200`	`application/json`	Grant key issued successfully	-	Pass `data.grantKey` to the app client.
`400`	`application/problem+json`	The request cannot be processed	-	-

Error codes by API

Code	Condition	How to handle
`provider_not_supported`	An unsupported `providerId` was sent.	Check that you specified `CUSTOM_PROVIDER` for `providerId`.
`provider_config_not_found`	No login method is configured for this app.	Check the login settings in the Hive Console.

Change the username password

PATCH /auth/v1/username/password

Changes the password of an account to which the username login method is connected. You can use it regardless of how the username was linked. When a user requests a password change in the app, the app server calls this API after it completes identity verification. When the Hive Axyl authentication server changes the password, it revokes the login sessions on all devices, including the current device. To handle this with the Hive Axyl SDK in the app client, see Change the password.

Before calling the API

Caller: app server
Base URL: https://core-api.hiveaxyl.com
Authentication: Authorization: Bearer {access-token}

Warning

The access token you put in the authentication header is not the token for the app server but the login token of the user whose password you change. Both the token and the password hashes are sensitive information, so do not leave them in logs or error messages.

Call parameters

Name	Location	Type	Required	Description
`X-App-Id`	`header`	`string`	`true`	The App ID registered in the Hive Console. If the header is not sent, the response is `missing_field`; if the value is empty, the response is `missing_app_id`.
`X-SDK-Version`	`header`	`string`	`false`	SDK version. The Hive Axyl SDK sends it when it makes the call.
`X-Platform`	`header`	`string`	`false`	Client platform identifier.
`X-OS-Version`	`header`	`string`	`false`	Client OS version.
`traceparent`	`header`	`string`	`false`	W3C Trace Context value. Used for distributed tracing.
`Accept-Language`	`header`	`string`	`false`	Client language. Used to apply localized messages.
`User-Agent`	`header`	`string`	`false`	Client User-Agent.
body	body	`UsernamePasswordChangeRequest`	`true`	Information about the password to change.

Request body UsernamePasswordChangeRequest

Field	Type	Required	Description
`currentPassword`	`string`	`true`	Current password. Send the 64-character lowercase hexadecimal string produced by converting the original password the user entered with `SHA256(raw_password)`.
`newPassword`	`string`	`true`	New password. Send a value converted in the same way as `currentPassword`. It must differ from `currentPassword`.

Call example

curl

curl -X PATCH 'https://core-api.hiveaxyl.com/auth/v1/username/password' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-App-Id: {app-id}' \
  -H 'Accept-Language: ko' \
  -d '{
    "currentPassword": "b94f6f125c79e3a5ffaa826f584c10d52ada669e6762051b826b55776d05a8f6",
    "newPassword": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'

Response

For the common data and meta, the error body, and the product common error codes, see Account and authentication responses and errors. This section describes the objects this API actually returns and the handling specific to this API.

The data of the success response is null. No value is returned other than the password change result.

Response example

200 OK400 Bad Request

{
  "data": null,
  "meta": null
}

{
  "type": "/errors/auth/same-password",
  "title": "Same Password",
  "status": 400,
  "detail": "The new password must be different from the current password.",
  "instance": "/auth/v1/username/password",
  "code": "same_password",
  "outcome": null
}

Notes for each API

When the password change succeeds, the Hive Axyl authentication server revokes the login sessions on all devices, including the current device. On the app server, pass the change result to the app client and guide the user to log in again with the new password.

token_revoke_failed means that the login sessions of this account could not be revoked. Send the same request again after a while.

Response status

Status	Content type	Meaning	Response header	Response body or handling
`200`	`application/json`	Password changed successfully	-	`data` is `null`.
`400`	`application/problem+json`	The request cannot be processed	-	-

Error codes by API

Code	Condition	How to handle
`same_password`	The new password is the same as the current password.	Guide the user to enter a different password.
`username_verify_failed`	The current password does not match.	Guide the user to enter the current password again.
`username_not_found`	The username account cannot be found.	Check the account status.
`provider_not_exist`	The username login method is not connected to this account.	Check whether the username is linked.
`token_revoke_failed`	Revoking the login sessions failed.	Send the same request again after a while.
`ip_blocked`	The access IP is blocked.	Inform the user that the IP is restricted from access.