ITokenService

A service that issues JWT tokens based on OAuth 2.0. Use it to exchange the authorization code returned by a login method of IAuthService for an access token and a refresh token, or to get new tokens with a refresh token.

Interface: ITokenService
Namespace: Hive.Axyl.Auth
Package: com.com2usplatform.hiveaxyl.auth

Token validation is a server API

The Hive Axyl SDK does not provide introspection, which the app server uses to check the validity of an access token. See Check access token validity.

Registration and retrieval

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddToken();
});

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

Method summary

Method	Authentication	Description
IssueTokenAsync	Not required	Issues tokens with one of an authorization code, a refresh token, or client credentials.

Methods

IssueTokenAsync

Issues tokens. The issuance method is determined by the type you pass as the request body.

Unity

Task<TokenIssueTokenResult> IssueTokenAsync(TokenRequest request, ApiCallContext? context = null);

The SDK automatically passes the App ID in the X-App-Id header, so do not put it in the request body.

Parameters

Parameter	Type	Required	Description
`request`	TokenRequest	Required	An instance of the subtype that matches the issuance method.
`context`	`ApiCallContext?`	Optional	Per-call settings. If omitted, the default values apply. See Call context.

Result

The returned object TokenIssueTokenResult branches into one of the following cases. The Data of Success contains TokenResponseData, and the other cases have no additional data.

Result case	Wire code	Description
`Success`	—	Token issuance succeeded.
`InvalidClient`	`invalid_client`	The client credentials are invalid.
`UnsupportedGrantType`	`unsupported_grant_type`	The `GrantType` is not supported.
`InvalidGrant`	`invalid_grant`	The authorization code is invalid or has expired.
`InvalidGrantExpired`	`invalid_grant_expired`	The authorization code has expired. You must start again from login.
`InvalidGrantCodeChallenge`	`invalid_grant_code_challenge`	The PKCE `CodeVerifier` does not match the `CodeChallenge` sent at login.
`InvalidGrantRefreshToken`	`invalid_grant_refresh_token`	The refresh token is invalid for a reason such as expiration, tampering, or reuse. Regardless of the reason, the user must log in again.
`AppNotFound`	`app_not_found`	The app information could not be found.
`TemporarilyUnavailable`	`temporarily_unavailable`	The server temporarily could not process the request. Do not retry immediately; send the same request again after an interval.
`UnknownOutcome`	`UNKNOWN`	A new result unknown to this SDK version.
`Failure`	`FAILURE`	The call could not be completed. Common Failure codes also branch into this case, and the cause is in `Failure.Problem.ExternalCode`.

Among the results for which the server responds with a code, TemporarilyUnavailable is the only one whose result can change if you try again. For the rest, the result is the same even if you send the same request again. Results whose names start with InvalidGrant mean that the authorization code or refresh token can no longer be used, so prompt the user to log in again.

Call example

Unity

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

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

var request = new AuthorizationCodeTokenRequest
{
    ClientId          = "{clientId}",
    AuthorizationCode = authorizationCode,   // Value returned by the login method
    CodeVerifier      = codeVerifier,        // Original of the codeChallenge used in the login request
};

TokenIssueTokenResult result = await token.IssueTokenAsync(request);

switch (result)
{
    case TokenIssueTokenResult.Success success:
        string accessToken = success.Data.AccessToken;
        string? refreshToken = success.Data.RefreshToken;
        break;

    case TokenIssueTokenResult.InvalidGrantExpired:
        // The authorization code has expired. Start again from login.
        break;

    case TokenIssueTokenResult.Failure failure:
        HiveError err = failure.Problem;
        break;

    default:
        // Unhandled results and UnknownOutcome
        break;
}

Refresh tokens are single-use

When you issue tokens with RefreshTokenTokenRequest, the refresh token you used becomes invalid immediately, and a new refresh token is issued as well. If you do not replace the stored value with RefreshToken from the response, the next refresh fails.

Data types

TokenRequest

abstract class — The token issuance request body. You cannot create an instance of it directly; use one of the following three subtypes. The issuance method is distinguished by the GrantType value that each subtype fixes.

Subtype	`GrantType`	Purpose
AuthorizationCodeTokenRequest	`authorization_code`	Exchange the authorization code received at login for tokens
RefreshTokenTokenRequest	`refresh_token`	Reissue tokens with a refresh token
ClientCredentialsTokenRequest	`client_credentials`	Issue a token for server-to-server communication

AuthorizationCodeTokenRequest

Issues user tokens based on PKCE. Use it to exchange the authorization code returned by a login method.

Field	Type	Required	Description
`GrantType`	`string`	Required	Fixed to `authorization_code`. Do not change the value.
`ClientId`	`string`	Required	The OAuth client identifier.
`AuthorizationCode`	`string`	Required	The authorization code received in the response of the login method. It is a value encrypted with AES-256-CBC.
`CodeVerifier`	`string`	Required	The original string of the `CodeChallenge` sent in the login request. It uses only the unreserved characters of RFC 7636 §4.1.

RefreshTokenTokenRequest

Reissues an access token and a refresh token with a refresh token.

Field	Type	Required	Description
`GrantType`	`string`	Required	Fixed to `refresh_token`. Do not change the value.
`ClientId`	`string`	Required	The OAuth client identifier.
`RefreshToken`	`string`	Required	The refresh token in RS256 JWT format. It must be the most recently issued value; previous values are already invalid.

ClientCredentialsTokenRequest

Issues a token to use for server-to-server communication. Only an access token is issued; no refresh token is issued.

Field	Type	Required	Description
`GrantType`	`string`	Required	Fixed to `client_credentials`. Do not change the value.
`ClientId`	`string`	Required	The OAuth client identifier.
`ClientSecret`	`string`	Required	The client secret.

Do not include the client secret in the app client

This method is used when the app server calls the Hive Axyl Server API. For the procedure for getting the token on the app server, see Issue a token.

TokenResponseData

The response contained in Success.Data when issuance succeeds.

Field	Type	Required	Description
`AccessToken`	`string`	Required	The issued access token.
`RefreshToken`	`string?`	Optional	The issued refresh token. It is not issued with the `client_credentials` grant type.
`ExpiresIn`	`long`	Required	The remaining validity time of the access token, in seconds.
`Meta`	`string?`	Optional	Additional information that the server sends along. It is contained as the raw, unprocessed JSON string.