Authentication token API

When the app server calls the Hive Axyl Server API directly, every request needs a JWT access token. The JWT access token is the credential the Hive Axyl server uses to identify who sent the request and which app it targets. This page describes the API the app server uses to issue this token and the API that checks whether a user's access token received from the app client is valid.

Prepare for token issuance

To issue a token, you need a security key issued in the Hive Console. A security key consists of a Client ID, which is a public identifier, and a Client Secret, which is a secret key. Check the two values in Project Settings > Security Key. If you have not issued a security key yet, see Security key.

Tokens for the app server are issued with the client_credentials grant type. This grant type gets an access token with only the Client ID and Client Secret, without user login, and is used for calls between the app server and the Hive Axyl server. This token is also called a master token.

Warning

Keep the Client Secret and the issued access token only on the app server, in secure storage. If either value is included in the app client or exposed externally, an unauthorized party can call the API in place of the app server.

Issue a token

POST /token/v1/issue

Issues a JWT access token for the app server with the Client ID and Client Secret. Call this API from the app server before you call any other Hive Axyl Server API.

Before calling the API

Caller: app server
Base URL: https://core-api.hiveaxyl.com
Authentication: Not required

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 information.
`X-Platform`	`header`	`string`	`false`	Client platform information.
`X-OS-Version`	`header`	`string`	`false`	Client operating system version information.
`traceparent`	`header`	`string`	`false`	W3C Trace Context header for distributed tracing.
`Accept-Language`	`header`	`string`	`false`	Response language setting.
`User-Agent`	`header`	`string`	`false`	User-Agent information of the client application.
body	body	`ClientCredentialsTokenRequest`	`true`	Token issuance request information.

Request body ClientCredentialsTokenRequest

Field	Type	Required	Description
`grantType`	`string`	`true`	Grant type for token issuance. Because you are issuing a token for the app server, specify `client_credentials`.
`clientId`	`string`	`true`	The Client ID you checked in Project Settings > Security Key. Up to 32 characters.
`clientSecret`	`string`	`true`	The Client Secret you checked in Project Settings > Security Key. Up to 64 characters.

Call example

curl

curl -X POST 'https://core-api.hiveaxyl.com/token/v1/issue' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-App-Id: {app-id}' \
  -d '{
    "grantType": "client_credentials",
    "clientId": "{client-id}",
    "clientSecret": "{client-secret}"
  }'

Response

For the common data and meta, the error body, and the product common error codes, see Authentication token 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.accessToken`	`string`	The issued JWT access token. Put it in the `Authorization` header of Hive Axyl Server API requests.
`data.refreshToken`	`string or null`	JWT refresh token. Always `null` with the `client_credentials` grant type.
`data.expiresIn`	`integer`	Time remaining until the access token expires. In seconds, counted from the time of issuance.

Response example

200 OK400 Bad Request

{
  "data": {
    "accessToken": "{access-token}",
    "refreshToken": null,
    "expiresIn": 3600
  },
  "meta": null
}

{
  "type": "/errors/token/invalid-client",
  "title": "Invalid Client",
  "status": 400,
  "detail": "The client credentials are invalid.",
  "instance": "/token/v1/issue",
  "code": "invalid_client",
  "outcome": null
}

Notes for each API

The client_credentials grant type does not issue refresh tokens. When the access token expires, call this API again to get a new token.

Reuse the issued token for multiple requests during expiresIn. If you issue a new token every time you call an API, unnecessary calls increase.

Response status

Status	Content type	Meaning	Response header	Response body or handling
`200`	`application/json`	Token issued successfully	-	`data` contains the issued token information.
`400`	`application/problem+json`	The request cannot be processed	-	-

Error codes by API

Code	Condition	How to handle
`invalid_client`	The Client ID or Client Secret is invalid.	Check the two values again in Project Settings > Security Key. If you replaced the Client Secret, also change the value applied to the app server.
`unsupported_grant_type`	An unsupported `grantType` was sent.	Check that you specified `client_credentials` for `grantType`.
`app_not_found`	The app information for `X-App-Id` cannot be found.	Check the App ID again in Project Settings > App ID.

Because tokens for the app server are issued only with the client_credentials grant type, the invalid_grant family of codes, which are returned only for other grantType values, does not occur in this call.

Use the issued token

Put the issued access token in the Authorization header of Hive Axyl Server API requests in the Bearer {access-token} format. The following are the headers you send when you call the Hive Axyl Server API. Check the request body in the description of the API you call.

curl

-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json' \
-H 'X-App-Id: {app-id}'

Which token to use

The token for the app server is a value the app server uses to prove its own identity, and it is different from an individual user's login token. The token you put in the Authorization header differs by Hive Axyl Server API, so check the following list.

Check access token validity: Token for the app server
Issue a pre-authorization key: Token for the app server
Change the username password: Login token of the user whose password you change
Verify consumable product receipts: Token for the app server
Verify subscription product receipts: Token for the app server
Get purchase history: Token for the app server
Send remote push notifications: Token for the app server

Check access token validity

POST /token/v1/introspect

The app server checks whether an access token received from the app client is genuine and gets back the Player ID of the token's owner. Call this API before processing that must not allow forgery or tampering, such as delivering items or saving play data. This way of checking token validity follows RFC 7662 Token Introspection, an OAuth 2.0 standard.

A token that is forged, expired, or revoked, or a token of a kind other than an access token, is returned not as an error but as a success response in which data.active is false. Do not decide by the HTTP status code alone; decide by the data.active value.

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 the token for the app server that you received from Issue a token. Put the user's access token that you want to verify in the token field of the request body, not in the authentication header. If you swap the two values, the request is rejected.

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	`IntrospectRequest`	`true`	Request body that contains the token to verify.

Request body IntrospectRequest

Field	Type	Required	Description
`token`	`string`	`true`	Access token of the user to verify. This is the value the app client read from `ISessionManager.AccessToken` and sent to the app server. Up to 4096 characters. It is sensitive information, so do not write it to logs.

Call example

curl

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

Response

For the common data and meta, the error body, and the product common error codes, see Authentication token 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.active`	`boolean`	Whether the token is valid. If `false`, the remaining fields below are not included in the response.
`data.playerId`	`integer`	Player ID of the token's owner. The app server uses this value as the basis for identifying the user.
`data.deviceKey`	`string`	Identifier of the device the token was issued to.
`data.expiresAt`	`string`	Token expiration time. In ISO 8601 format.

Response example

200 OK valid token200 OK invalid token400 Bad Request

{
  "data": {
    "active": true,
    "playerId": 100000123,
    "deviceKey": "0f8e7d6c5b4a493882716f5e4d3c2b1a",
    "expiresAt": "2026-01-01T00:00:00Z"
  },
  "meta": null
}

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

{
  "type": "/errors/token/introspect-project-mismatch",
  "title": "Introspect Project Mismatch",
  "status": 400,
  "detail": "The target token's project does not match the caller.",
  "instance": "/token/v1/introspect",
  "code": "introspect_project_mismatch",
  "outcome": null
}

Notes for each API

Process the request only when data.active is true, and use data.playerId from the response, not the Player ID the app client sent with it, as the basis for identifying the user. Values the app client sends can be forged.

If data.active is false, the token is forged, expired, or already revoked, or it is a token of a kind other than an access token. Reject the request on the app server, and respond so that the app client logs in again and gets a new token.

You cannot use this API to verify a token that belongs to another project. If the token for the app server and the token being verified belong to different projects, the request is rejected with introspect_project_mismatch.

Response status

Status	Content type	Meaning	Response header	Response body or handling
`200`	`application/json`	Normal response that passed caller authentication and authorization	-	Token validity is identified by `data.active`.
`400`	`application/problem+json`	The request cannot be processed	-	-

Error codes by API

Code	Condition	How to handle
`introspect_forbidden`	The caller does not have permission to check token validity.	Check that you put the token for the app server that you received from Issue a token in the authentication header, and that the token for the app server and the token being verified belong to the same project.
`introspect_project_mismatch`	The token being verified belongs to a different project from the caller.	Check the App ID used in the call and the project of the token for the app server.