X login practical guide
X login is a feature that lets users log in to your app with their X account. X authenticates the user, and the app gets a Hive Axyl login session from the authentication result. Once the session is activated, the Hive Axyl SDK can identify the logged-in user.
To implement it, you must put together, in order, the X Developer Portal settings, the Hive Console settings, the installation of the Hive Axyl SDK and the web login session Add-on, recipe code calls, and app code. With the recipe, you can bundle the calls from opening the X login page to activating the Hive Axyl login session into one.
X has no dedicated native Add-on, so it uses the web login session on all of Android, iOS, macOS, and Windows.
Implementation scope
The work required to implement X login starts with preparing OAuth credentials in the X Developer Portal and ends with handling the login result in the app.
The work in each step falls into one of the following six categories.
| Category | Owner | Description |
|---|---|---|
| External console | App operator | Settings you configure in the X Developer Portal. |
| Hive Console | App operator | Settings that enable X login and register credentials in the Hive Console. |
| Hive Axyl SDK | App developer | The work of installing and initializing the authentication, token, and session modules, and the SDK methods used for login. |
| Add-on | App developer | The Hive Axyl SDK WebAuth extension package that opens the X login page in a browser. |
| Recipe code | App developer | Source code that bundles the calls from getting X credentials to activating the session. |
| App code | App developer | Parts you implement directly: the login screen, storing OAuth settings, preparing the redirect URI, and handling the screen for each result. |
This practical guide has no step that calls the Hive Axyl Server API directly. If you leave WebAuthOptions.TokenEndpoint empty, the recipe uses ExchangeProviderTokenAsync() of the Hive Axyl SDK. If you specify a value, the recipe directly calls X's token endpoint and user information endpoint. In either method, the app does not call Hive Axyl Server API endpoints directly.
Recipe
The Hive Axyl SDK provides opening a web login session, exchanging external authorization codes, Hive Axyl login, token issuance, and session activation as separate calls. The recipe combines this sequence and runs it with a single LoginWithProviderAsync() call.
A recipe is plain C# source code that you copy into your project instead of installing as a package.
| Category | Location | Characteristics |
|---|---|---|
| Hive Axyl SDK | Unity package com.com2usplatform.hiveaxyl.* | You install and use it. It provides authentication features as fine-grained methods. |
| Common recipe | Assets/Recipes/ProviderLogin/ | Provides ProviderLoginRecipe, result types, and common code that uses credential sources. |
| X recipe | Assets/Recipes/ProviderLogin.WebAuth/ | Provides XCredentialSource and common web login session code. |
| Usage example | Assets/RecipeExamples/Authentication/ProviderLoginExample.cs | Code you read for reference. Its comments explain the login flow common to all external authentication providers and the parts the app must implement for each result. |
Only the web login session recipe is provided for X
XCredentialSource builds the X OAuth authorization URL, verifies the callback, and then prepares the X credentials. ProviderLoginRecipe uses these credentials to continue with Hive Axyl login, token issuance, and session activation.
OSs supported by the recipe
The X credential source is used on the following OSs, where the WebAuth Add-on works.
| OS | Authentication method | Credential source | Implementation method |
|---|---|---|---|
| Android, iOS, macOS, Windows | Browser web login session | XCredentialSource | Follow the procedure in this guide. |
If you call it on an OS where the web login session Add-on is not registered or in the Unity Editor, an Unavailable error is returned. This does not mean that X account authentication was rejected; it means that the browser authentication session cannot run in that environment.
What the app implements
The recipe handles only the steps from getting credentials to activating the session on the app's behalf. Implement the following items in the app.
- The login screen and the screen transition after login
- Storing the X OAuth Client ID, authorization endpoint, Scope, and redirect URI
- Checking that the Callback URI registered in the X Developer Portal matches the app settings
- Preparing the redirect URI for each OS
- Selecting the token endpoint and the user information endpoint to use in the public client method
- Creating and storing
DeviceKey - Storing the session token received from login
- Retries and user guidance based on the login result
Do not include the X Client Secret in the app. In the public client method, the recipe communicates directly with the X token endpoint using PKCE, and in the server exchange method, the Client Secret is kept only in the Hive Console.
Common prerequisites
Before you start implementing, prepare the following items.
| Item to prepare | Required | Category | Where to check |
|---|---|---|---|
| OAuth Client ID, Callback URI, and Scope in the X Developer Portal | Required | External console | X login integration |
| Create a project | Required | Hive Console | Create a project |
| Create an App ID | Required | Hive Console | Create an App ID |
| Register X login credentials and enable X login | Required | Hive Console | X(Twitter) login credentials, Login method types |
| Check the Client ID | Required | Hive Console | Get the security key |
| Connect the SDK to your Unity project | Required | Hive Axyl SDK | Connect the SDK to your Unity project |
Client ID is the value you check in the Hive Console, and WebAuthOptions.ClientId is the OAuth client ID issued by the X Developer Portal. Do not swap the two values. X login requires PKCE, so the recipe generates new PKCE values for each login attempt.
Next steps
Once you have completed the prerequisites, start Implement X login.