Issue a token

The username login method does not create a login session right away. Instead, it returns an authorizationCode that is valid for only 180 seconds after issuance. You must use this authorizationCode as input to issue an access token and a refresh token before you can register the session in the next step.

The token issuance request uses GrantType, ClientId, AuthorizationCode, and CodeVerifier.

1. Prepare the call parameters for the token issuance method

Prepare the parameters required for token issuance.

GrantType

Use authorization_code.

ClientId

This is the Client ID that the Hive Console issues per project. All App IDs in the same project use the same value. Check the value in Get the security key.

AuthorizationCode

Use the AuthorizationCode from the username login response. It expires 180 seconds after issuance, so call this method right after login.

CodeVerifier

For CodeVerifier, pass the codeVerifier that pairs with the codeChallenge you sent when you called the username login method.

2. Issue an access token and a refresh token

IssueTokenAsync

Call IssueTokenAsync() to issue an access token and a refresh token with the authorizationCode. When you issue tokens with an authorization code, use AuthorizationCodeTokenRequest.

Call parameters

Field name	Type	Required	Description
request	TokenRequest	Required	Token issuance request. For token issuance that uses an authorization code as input, use `AuthorizationCodeTokenRequest`.
context	ApiCallContext	Optional	Per-call settings object. If omitted, the default values are used.

AuthorizationCodeTokenRequest

Field name	Type	Required	Description
`GrantType`	string	Required	Fixed to `authorization_code`
`ClientId`	string	Required	Client ID of the console security key issued per project
`AuthorizationCode`	string	Required	`AuthorizationCode` from the login response
`CodeVerifier`	string	Required	`codeVerifier` that pairs with the `codeChallenge` sent in the login call

Call example

For the result model and handling principles of common failures (Failure) that prevent the request from being performed, see Common error handling.

Unity

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

ITokenService token = HiveCore.Resolve<ITokenService>();

// authorizationCode is Data.AuthorizationCode from the [username login] response,
// and codeVerifier is the value that pairs with the codeChallenge used in that login call.
// TokenIssueTokenResult object
var issueResult = await token.IssueTokenAsync(new AuthorizationCodeTokenRequest {
    GrantType    = "authorization_code",
    ClientId     = "{clientId}",
    AuthorizationCode = authorizationCode,
    CodeVerifier = codeVerifier,   // Pairs with the codeChallenge sent in the login call
});
if (issueResult is not TokenIssueTokenResult.Success issued)
{
    // Handle token issuance failures (InvalidGrant, InvalidGrantCodeChallenge, and so on)
    return;
}

Response data

On success, the tokens are contained in Data (TokenResponseData) of TokenIssueTokenResult.Success.

Field name	Type	Required	Description
`Data.AccessToken`	string	Required	Access token used to call methods that require authentication
`Data.RefreshToken`	string?	Optional	Refresh token used for token refresh. The type is nullable, but it is returned for token issuance with the `authorization_code` grant type.
`Data.ExpiresIn`	long	Required	Time remaining, in seconds, from issuance until the access token expires. It does not apply to the expiration of the refresh token. Use it to calculate the expiration time in the next step, Activate the session.

Response example

Unity

// TokenIssueTokenResult.Success issued
// issued.Data.AccessToken  = "eyJhbGciOi..."   // Used to call methods that require authentication
// issued.Data.RefreshToken = "def502..."        // Used for token refresh (returned for token issuance with the authorization_code grant type)
// issued.Data.ExpiresIn    = 3600               // Time remaining until expiration (seconds)

Response status

We recommend handling the response cases of TokenIssueTokenResult with a switch statement. For the cases that you do not handle explicitly, we recommend handling them safely in default.

Response case	Description	App client handling
`Success`	Token issuance succeeded. `Data` contains the tokens.	Register the session with `SetSession` in the next step
`InvalidGrant`	The authorization code is invalid	Start again from login
`InvalidGrantExpired`	The authorization code has expired	Start again from login
`InvalidGrantCodeChallenge`	`codeVerifier` does not match the `codeChallenge` sent at login	Check the PKCE pair
`InvalidGrantRefreshToken`	The refresh token is invalid. This occurs only for token issuance with the `refresh_token` grant type.	Start again from login
`InvalidClient`	The Client ID is invalid	Check the console security key
`UnsupportedGrantType`	The `GrantType` is not supported	Check that it is `"authorization_code"`
`AppNotFound`	The app information cannot be found	Check the app registration status in the console
`TemporarilyUnavailable`	The server temporarily could not process the request. Unlike other response cases that the server determined, such as `InvalidGrant`, sending the same request again may produce a different result.	Do not resend it right away; retry the same request after an interval
`UnknownOutcome`	A new result unknown to this SDK version	Log it and handle it conservatively
`Failure`	Common Failure. Missing or malformed required parameters (`invalid_parameter`), missing required fields (`missing_field`), and a missing `X-App-Id` header (`missing_app_id`) also fall into this case. The cause is contained in `Failure.Problem.ExternalCode`. See Common error handling.	Handle according to the common error handling criteria

Next steps

Activate the session