OAuth 2.0 uses short-lived tokens with long-term authorization (refresh tokens) instead of long-lived tokens. A refresh token allows users to stay in your application for an extended period of time without needing to re-enter their username and password. This eliminates the risk of compromising user authentication data.

Set up OAuth 2.0 for authorization:

• via username or email and password
• via social networks
• via Steam

If the option is enabled, user registration and authentication is carried out by calling the Register new user and JWT auth by username and password API calls. The Login & Account System asset provides the same methods for OAuth 2.0 authorization as for JWT token authorization. When the engine first initializes an object on the scene, the Awake method is called. The method checks the expiration of the current refresh token.

To configure OAuth 2.0 authorization:

1. Set up OAuth 2.0 authentication for Login project in your Publisher Account.
2. Set up asset in your Unity project.

Set up OAuth 2.0 authentication for Login project in your Publisher Account

1. Go to your Publisher Account.
2. Click Login in the side menu.
3. Click Configure in the Login project pane.
4. Go to the Security block and select the OAuth 2.0 section.
5. Click Add OAuth 2.0.
6. Specify OAuth 2.0 redirect URIs and click Connect.
7. Copy and save the Client ID.

Set up asset in your Unity project

1. Go to your Unity project.
2. Click Window > Xsolla > Edit Settings in the main menu.
3. In Inspector panel:
   1. In the Authorization method field, select OAuth2.0.
   2. In the OAuth2.0 client ID field, specify Client ID received when setting up OAuth 2.0 in Publisher Account.

The following methods are implemented in Login & Account System asset to work with refresh tokens:

• IsOAuthTokenRefreshInProgress — returns true during refresh token process, false otherwise.
• ExchangeCodeToToken — exchanges the user’s authentication code for a valid JWT.

The oauthState argument found in the GetSocialNetworkAuthUrl method is used for additional user verification during OAuth 2.0 authentication. This argument is used to mitigate possible CSRF attacks.

You can integrate Game Commerce and Cross-Buy assets with your own login system. To do this, implement user authentication in your application via Pay Station access token.

The flow of interaction with Xsolla servers when using your own authorization system:

1. Your client sends an authentication request to your server.
2. Your server authorizes the user and sends a request to the Xsolla server to receive the Pay Station access token.
3. Xsolla server returns the Pay Station access token.
4. Your server passes the Pay Station access token to the client.
5. SDK methods use the received Pay Station access token as an authorization token to open an in-game store, make a payment, and manage inventory.

Get Pay Station access token

On the back end of your application, implement a method to obtain a Pay Station access token using an HTTP POST request.

Xsolla API uses basic HTTP authentication. The request must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant_id:api_key encoded according to the Base64 standard. You can find the parameter values in Publisher Account:

• for merchant_id, go to the Project settings > Webhooks > Merchant ID section.
• for api_key, go to the Company settings > API key section.

HTTP request:

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Headers:
  Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Body:
  {
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "amount": 1,
          "sku": "SKU01"
        }
      ]
    }
  },
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 16184,
    "ui": {
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      },
      "desktop": {
        "virtual_item_list": {
          "button_with_price": true,
          "layout": "list"
        }
      },
      "size": "medium"
    }
  },
  "user": {
    "country": {
      "allow_modify": true,
      "value": "US"
    },
    "age": 19,
    "email": {
      "value": "john.smith@mail.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    }
  }
}

curl --request POST \
  --url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"age":19,"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"age":19,"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic <your_authorization_basic_key>"
    }

conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

var data = JSON.stringify({
  "user": {
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "age": 19, 
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 16184,
    "currency": "USD",
    "language": "en",
    "ui": {
      "size": "medium",
      "desktop": {
        "virtual_item_list": {
          "layout": "list",
          "button_with_price": true
        }
      },
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      }
    }
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "sku": "SKU01",
          "amount": 1
        }
      ]
    }
  }
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

To get the token, pass the following parameters in the request body:

See examples of requests and responses in the API reference.

Use user JWT

To use the Pay Station access token to open an in-game store, make a payment, and manage inventory, pass it to the XsollaLogin.Instance.Token and XsollaStore.Instance.Token properties in the SDK methods.

See examples of using the authorization token in the tutorials:

• Sell virtual items for real currency
• Sell virtual items for virtual currency
• Display of virtual currency balance
• Display of items in inventory

Implement the logic of receiving a new Pay Station access token after its expiration. It is recommended that you get a new token in the background mode, so the user doesn’t have to log in to the application again.

Native authentication lets users log in to your application via a social network account configured on a mobile device.

The first time a user logs in, the social networking application is launched and asks for permission to authenticate the user. After that, authentication is performed automatically without requiring the user to do anything.

Currently, SDK has implemented native authentication via the following social networks:

• Google
• Facebook
• WeChat
• QQ

To configure native authentication:

1. Create your Unity project build for Android.
2. Configure the application in the developer account for the social network:
   1. For authentication via Facebook:
      1. Register and create a new application.
      2. Set up the application page in your Facebook developer account.
   2. For authentication via Google, set up the project in Google API Console.
   3. For authentication via WeChat:
      1. Register and create a new application.
      2. Submit the application for review.
   4. For authentication via QQ:
      1. Register and create a new application.
      2. Submit the application for review.

3. Set up authentication via social networks on the Xsolla side:
   1. For Facebook and Google, set up social connections in Publisher Account.
   2. For WeChat and QQ, contact your Account Manager.
4. Set up the asset for your Unity project.

Create Unity project build for Android

1. Go to your Unity project.
2. Click File > Build settings in the main menu.
3. Click Android in the Platform panel.
4. Click Build.
5. Make sure that the hash key is formed:
   1. Click Window > Xsolla > Edit Settings in the main menu.
   2. Make sure that the hash key appears in the Android debug hash key field.

For further native authentication configuration you will need:

• Package Name found in the Inspector panel after selecting the Android platform in File > Build settings.
• Android class name found in Window > Xsolla > Edit Settings > Inspector > Android class name.
• Android debug hash key found in Window > Xsolla > Edit Settings > Inspector > Android debug hash key.

Set up application page in your Facebook developer account

1. Go to project settings in the Facebook developer account.
2. Go to Settings > Basic.
3. Click Add Platform and select Android.
4. Specify Package Name from your Unity project in the Google Play Package Name field.
5. Specify Android class name from your Unity project in the Class Name field.
6. Specify Android debug hash key from your Unity project in the Key Hashes filed.
7. Click Save Changes.

For further native authentication configuration, you will need App ID and App Secret found in project settings in Settings > Basic section.

Set up project in Google API Console

1. Go to Google API Console.
2. Click New Project.
3. Specify Project name and Location and click Save.
4. Go to the created project and click OAuth consent screen in the side menu.
5. Select External option and click Create.
6. Specify the necessary parameters and click Save.
7. Click Credentials in the side menu.
8. Create an OAuth 2.0 client for your Unity application:

1. 1. Click Create credentials and select OAuth client ID.
   2. Specify Android in the Application type field.
   3. Specify Name.
   4. Specify Package Name from your Unity project in the Package name field.
   5. Specify Android debug hash key from your Unity project in the SHA-1 certificate fingerprint field.
   6. Click Create.
   7. Click OK.

9. Create an OAuth 2.0 client for the web application:
   1. Click Create credentials and select OAuth client ID.
   2. Specify Web application in the Application type field.
   3. Specify Name.
   4. Click Add URI in the Authorized redirect URIs section and specify https://login.xsolla.com/api/social/oauth2/callback URI.
   5. Click Create.
   6. Click OK.

For further native authentication configuration, you will need Client ID and Client Secret found in settings of the Client ID for the web application.

Set up social connections for Login project in Xsolla Publisher Account

1. Open your project in Publisher Account.
2. Click Login in the side menu and go to Login projects > your Login project > Social connections.
3. To set up authentication via Facebook:

1. 1. Click Edit in the Facebook panel and change status to Disconnected.
   2. Specify the App ID from the Facebook developer account in the Application ID field.
   3. Specify App Secret from the Facebook developer account in the Application Secret field.
   4. Click Connect.

4. To set up authentication via Google:
   1. Click Edit in the Google panel and change status to Disconnected.
   2. Specify the Client ID for a web application from the Google API Console in the Application ID field.
   3. Specify the Client Secret for a web application from the Google API Console in the Application Secret field.
   4. Click Connect.

Set up asset for your Unity project

1. Go to your Unity project.
2. Click Window > Xsolla > Edit Settings in the main menu.
3. Specify the application ID:
   1. Specify App ID from the Facebook developer account in the Facebook App ID field.
   2. Specify Client ID for a web application from the Google API Console in the Google server ID field.
   3. Specify AppID from the WeChat application settings in the WeChat App ID.
   4. Specify AppID from the QQ application settings in the QQ App ID.
   Was this article helpful?

   Yes

   No

   Thank you!

   Is there anything we can improve? Message Send

   We’re sorry to hear that

   Please explain why this article wasn’t helpful to you. Message Send

   Thank you for your feedback!

   We’ll review your message and use it to help us improve your experience.
   Hide

Native authentication allows players to enter your application via the installed Steam application.

To set up native authentication:

1. Set up silent authentication via Steam in Publisher Account.
2. Configure your Unity project.
3. Configure processing of events.
4. Ensure authentication via Steam.

Configure your Unity project

1. Manually create a steam_appid.txt file and type your application ID in Steam there. Then, place this file to the Assets catalog of your project.

2. Open your Unity project.
3. In the main menu, go to Window > Xsolla > Edit Settings.
4. In the Inspector panel:
   1. Check the Use Steam authorization box.
   2. In the Steam App ID field, specify your application ID in Steam. The value should be the same as the value in the steam_appid.txt file.

Configure processing of events

To authenticate users via Steam, you should get a session ticket via the SteamAuth method. Pass the received value when calling the RequestTokenBy method. As a result, you get the token that is used when calling the API.

Ensure authentication via Steam

1. Create the build of your Unity project for a stand-alone platform.
2. Launch Steam and log in.
3. Launch your application. If everything is correct, the Steam pop-up window appears.

Token invalidation allows for improved security of user authentication data in your application. If the option is enabled, a new token replaces the old one that becomes invalid every time the user authenticates.

When using SDK, invalidation of the existing token and generation of a new one is made by calling Auth by username and password and Auth via social network API calls, if the with_logout parameter has the 1 value.

To enable token invalidation in your Unity project:

1. In the main menu, go to Window > Xsolla > Edit Settings.
2. In the Inspector panel, check the Enable JWT invalidation box.

You can use Xsolla Launcher to deliver your application to users and update it. The Launcher contains a built-in authorization tool. To avoid the need to re-enter username and password, set up authorization in your application via the Launcher.

Set up SDK and Launcher to work together

1. Set up Launcher in your Publisher Account.

2. Customize the launcher UI.

3. Implement the Launcher authorization logic in your application.
4. Generate a launcher installation file and a build archive.
5. Create an application build.
6. Upload the application build to the Xsolla update server.

Implement logic for authentication via Launcher

The flow for authorization in the application via Launcher is as follows:

1. The user is authorized in Launcher.
2. The user installs and runs the application.
3. Launcher runs the application and passes user parameters via the command line. The authorization token is passed in the xsolla-login-token parameter.
4. The application processes command line parameters and obtains a token. An example of a token processing script can be viewed in the demo project.
5. The application validates the received token. An example of a token validation script can be viewed in the demo project.
6. The application automatically authorizes the user without displaying an authorization page. An example of a user authorization script can be viewed in the demo project.

Create an application build

1. Go to your Unity project.
2. Click Window > Xsolla > Edit Settings in the main menu. In the Inspector panel:
   1. In the Project ID field, specify the Project ID found in Publisher Account > Project settings > Project ID.
   2. In the Login ID field, specify the Login ID found in Publisher Account > Launcher > General settings > Authentication.

3. Run the user authorization scene, where the token is processed.
4. Click File > Build settings in the main menu and then click Add Open Scenes. Make sure the authorization scene is added first in the list.
5. Click Build.
6. In the pop-up window, specify the path to the directory where the finished build will be placed.

Device ID authentication lets users start using the application on a mobile device without entering registration data. The first time a user logs in to the application using the device ID, a new account is created automatically, and the user doesn’t need to enter a username, email address, or other data.

With the device ID, you can implement user authentication on one or more mobile devices in the background mode. To use this function, the user should link the device ID to an existing account.

The SDK supports authentication via ID of mobile devices on Android and iOS.

Get device ID

The device ID is generated by the platform and is available to applications installed on the mobile device. The SDK gets the ID value using the platform API and uses this value to perform various functions using the Xsolla API.

The iOS device ID is passed in the UIDevice.identifierForVendor property. The standard Unity method SystemInfo.deviceUniqueIdentifier is used to determine the ID.

The Android device ID is passed in the android.provider.Settings.Secure.ANDROID_ID constant. The SDK uses its own logic to determine the ID because the standard Unity method returns the Android device ID as an MD5 hash, which is inappropriate for Xsolla API calls.

SDK methods

The SDK implements methods for the following functions:

Authentication

Account upgrade

Device management