Skip to content

Apply additional security

Guest accounts and username accounts are not verified by an external authentication provider. Therefore, accounts can be created without limit through requests from a forged app client alone. The grant key is a pre-authorization value that prevents this risk. The app server gets a grant key issued by the Hive Axyl authentication server and passes it to the app client. When the app client sends this value with the account creation request, the Hive Axyl authentication server processes only requests that the app server approved in advance.

The grant key is a single-use value that is valid for only 60 seconds after issuance. Once it is used in an account creation request, it is consumed immediately and cannot be reused.

Turn on additional security by selecting Apply additional security in the login settings of the Hive Console, and turn it off by selecting Additional security applied again. From the moment you apply it, all account creation requests without a grant key are rejected, so apply it only after you finish implementing both grant key issuance on the app server and grant key delivery on the app client. For the procedure to turn it on and off in the console, see Login settings.

Implementation order

Verification of the grant key is handled jointly by the app server, the app client, and the Hive Axyl authentication server.

  1. The app client requests account creation from the app server. At this point, the app server determines whether the request is legitimate according to its own policy.
  2. The app server calls Issue a pre-authorization key to get a grant key. The app server calls this API; the Hive Axyl SDK does not provide an issuance method.
  3. The app server passes the received grant key to the app client.
  4. When the app client calls the account creation method, it sends the value in the GrantKey field of the request object.
  5. The Hive Axyl authentication server verifies the grant key. If it is valid, the server processes the account creation; if it is invalid or missing, the server rejects the request.

The grant key must be consumed within 60 seconds, so handle steps 2 through 4 in sequence without waiting for user input.

Issue a grant key

The app server requests a grant key by specifying the type of authentication action to authorize. The authentication action types are as follows.

  • GUEST_CREATE: Guest account creation
  • USERNAME_CREATE: Username account creation
  • CUSTOM_LOGIN: Custom account login
  • CUSTOM_LINK: Custom account linking

The response returns grantKey and the issuance time. For the request fields and response details, see Issue a pre-authorization key.

Custom accounts always require a grant key regardless of the additional security setting. For how to implement it, see Link a custom account.

Values the Hive Axyl SDK provides

The Hive Axyl SDK provides fields in account creation requests for sending the grant key that the app server obtained.

You can send GrantKey even when additional security is turned off. The Hive Axyl authentication server always verifies and consumes the sent value, regardless of the setting. So that account creation is not rejected the moment additional security is turned on in the Hive Console, we recommend implementing your app to always send the grant key that the app server obtained.

Response status

The results that account creation methods return in relation to the grant key are as follows. For the other results, see the response status in each account creation document.

Response case Description App client handling
InvalidGrantKey When the grant key is invalid or has expired Get a new grant key issued through the app server and retry
GrantRequiredMissing When GrantKey was not sent for an app with additional security applied Check that the grant key delivery flow works