Exchange external authorization codes

In the Authorization Code flow, the only value that the Add-on returns is the external authentication provider's authorization code. The Hive Axyl authentication server cannot verify this authorization code directly. Before the login request, exchange it for credentials that can be verified.

The Hive Axyl authentication server performs the exchange by communicating directly with the external authentication provider's token endpoint, and returns the user identifier (ProviderUserId) and the authentication result (ProviderToken) as the result. Use these two values as the call parameters of Log in with an external authentication provider.

The login methods that need the exchange step are Google account, Apple, Google Play Games, and X. Combinations that follow the Direct Token flow do not have this step.

1. Prepare the call parameter values

Prepare the call parameters of the external authorization code exchange method.

ProviderCode

The external authentication provider's authorization code that the Add-on returned. Where you get the value differs for each login method.

Google account: The code parameter of the web login session callback
Apple: The code parameter of the web login session callback
Google Play Games: The ServerAuthCode returned by the Google Play Games login Add-on
X: The code parameter of the web login session callback

RedirectUri

Enter the redirect URI used in the authorization request exactly as is, without changing a single character. If the value differs even slightly, the external authentication provider rejects the exchange. If query parameters were attached to redirect_uri in the authorization URL, enter the entire string including those parameters.

Google account, X: The value you put in redirect_uri of the authorization URL
Apple: The Hive Axyl relay URL you put in redirect_uri of the authorization URL. This is a different value from the app callback URL you put in OpenRequest.RedirectUri
Google Play Games: The redirect URI registered in the Web application type OAuth client that the app server uses. Google Play Games does not build an authorization URL, so use this value

CodeVerifier

The PKCE value that the external authentication provider requires. Enter the codeVerifier that the app generated and stored before building the authorization URL, as is. This value is separate from the PKCE value for the Hive Axyl authentication server.

X: Required
Google account: Needed only if you put code_challenge in the authorization URL
Apple, Google Play Games: Do not specify

2. Exchange external authorization codes

ExchangeProviderTokenAsync

Call ExchangeProviderTokenAsync() to exchange the external authentication provider's authorization code for credentials to use for login. Calling this method alone does not complete login. Continue by calling Log in with an external authentication provider with the exchange result.

Call parameters

Field name	Type	Required	Description
request	ProviderTokenRequest	Required	External authorization code exchange request
context	ApiCallContext	Optional	Per-call settings object. If omitted, the default values are used.

ProviderTokenRequest

Field name	Type	Required	Description
`ProviderId`	`Provider`	Required	The login method for the exchange. One of `Google`, `SigninApple`, `GooglePlayGames`, and `X`
`ProviderCode`	string	Required	Authorization code issued by the external authentication provider
`RedirectUri`	string?	Optional	A value identical, character for character, to the redirect URI used in the authorization request. Required for `Google`, `GooglePlayGames`, and `X`. For `SigninApple`, it is required when you exchange an authorization code received through a web login session; enter the Hive Axyl relay URL that you put in `redirect_uri` of the authorization URL.
`CodeVerifier`	string?	Optional	PKCE `codeVerifier` for the external authentication provider. Required for `X`; for `Google`, include it only if you put `code_challenge` in the authorization URL. Do not include it for `SigninApple` and `GooglePlayGames`.

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;
using UnityEngine;

IAuthService auth = HiveCore.Resolve<IAuthService>();

// providerCode is the authorization code received from the Add-on,
// and codeVerifier is the PKCE value that the app stored before building the authorization URL.
var result = await auth.ExchangeProviderTokenAsync(new ProviderTokenRequest {
    ProviderId   = Provider.X,
    ProviderCode = providerCode,
    RedirectUri  = redirectUri,
    CodeVerifier = codeVerifier,
});

switch (result)
{
    case AuthExchangeProviderTokenResult.Success success:
        // Exchange succeeded → call external authentication provider login with these two values.
        string providerUserId = success.Data.ProviderUserId;
        string providerToken  = success.Data.ProviderToken;
        break;

    case AuthExchangeProviderTokenResult.ProviderTokenError:
        // Authorization code verification failed → prompt the user to authenticate again with that login method
        break;

    case AuthExchangeProviderTokenResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // Safety net: unhandled results and unknown new results (UnknownOutcome)
    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Warning

ProviderCode and ProviderToken are the user's credentials. Do not record them in logs, crash reports, or analytics events.

Response data

On success, the result is in Data (ProviderTokenResponseData) of AuthExchangeProviderTokenResult.Success.

Field name	Type	Required	Description
`Data.ProviderUserId`	string	Required	User identifier issued by the external authentication provider. Use it as `ProviderUserId` in the login request.
`Data.ProviderToken`	string	Required	Authentication result received from the exchange. Use it as `ProviderToken` in the login request. It contains the `id_token` for Google accounts and Apple, and an access token for Google Play Games and X.
`Data.ProviderId`	`Provider`	Required	Login method used for the exchange

Response example

Unity

// Example of success.Data in the Success branch
// success.Data.ProviderUserId = "20394809238"   // ProviderUserId of the login request
// success.Data.ProviderToken  = "..."           // ProviderToken of the login request
// success.Data.ProviderId     = Provider.X

Response status

We recommend handling the response cases of AuthExchangeProviderTokenResult with a switch statement.

Response case	Description	App client handling
`Success`	Exchange succeeded. Proceed with login using `Data.ProviderUserId` and `Data.ProviderToken`.	Call Log in with an external authentication provider
`ProviderNotSupported`	When the login method is not supported	Check the requested `ProviderId` value
`ProviderTokenExchangeNotSupported`	When the login method does not support the exchange step	Check the behavior flow of that login method
`ProviderTokenError`	When authorization code verification fails	Prompt the user to authenticate again with that login method
`ProviderRequestFailed`	When the Hive Axyl authentication server cannot communicate with the external authentication provider	Retry after a while
`ProviderConfigNotFound`	When the console has no settings for this login method	Check the login settings in the console
`ProviderClientInfoNotExists`	When the console has no client information for this login method	Check the login settings in the console
`AppNotFound`	When the app information cannot be found	Check the app registration status in the console
`TerminateService`	When the app's service has ended	Check the service operation status
`UnknownOutcome`	A new result that this SDK version does not recognize	Log it and handle it conservatively
`Failure`	Common Failure. Missing required parameters or format errors (`invalid_parameter`), missing required fields (`missing_field`), and a missing `X-App-Id` header (`missing_app_id`) also branch here, and the cause is in `Failure.Problem.ExternalCode`. See Common error handling.	Handle according to the common error handling criteria

Next steps

Log in with an external authentication provider