Set up user authentication

Authentication allows users to buy items in the Web Shop and see unique offers in the catalog.

Key features of the Web Shop with authentication:

Multiple authorization methods in the Web Shop.
Set up personalized storefronts and promo codes for authorized users.
Compliance with regional laws and regulations for the protection and processing of personal data.
Rate limit and DDoS protection.

You can choose one of the following authentication methods:

User ID authentication:
- Simplifies the integration of the Web Shop with the game.
- The authentication widget does not require registration or password entry. A user simply needs to enter the user ID from the game or use the same social network account for login as for logging in to the game.

Use user ID authentication if Xsolla Login isn’t set up in your game.

User ID and deep link authentication:
- Deep links can be used as an additional authentication method when logging in via User ID.
- The User ID and deep link authentication widget does not require registration or password entry. The user simply needs to enter their User ID from the game or log in via the game using a deep link.

Use User ID and deep link authentication if your game supports deep links for authentication.

Deep link authentication:

Use deep link authentication if your game supports deep links for authentication.

Authentication via Xsolla Login:
- Provides a wide range of authorization methods: social networks, one-time codes or links, and login and password.
- Allows you to customize the Xsolla Login widget.
- You can impose age restrictions on authorization.

Use Xsolla login authentication if this solution is already set up in your game.

For any of the authentication method, you can add a Fast Login block to your site.

User flow

The user goes to Web Shop with user ID authentication configured.
The user authorizes in the Web Shop in one of the following ways:
- The user enters their ID in the Fast Login block and clicks the login button.
- The user clicks the buy button for the selected item or the login button on the top bar:
  1. A modal window for entering the user ID or logging in through a social network opens.
  2. User enters their ID and clicks Continue or clicks on the social networks icon to choose a social network and completes authentication on the social network page.

The system checks if a user exists in the game. If a user with this ID or social account exists in the game, the user is authorized in the Web Shop. Otherwise an error message is displayed.

How to get it

On your application’s side, implement handling of the user validation webhook.

When receiving a webhook, the application should do the following:

Search for a user by their ID passed in the webhook.
Depending on the result, send one of the following status codes:
- 200 HTTP-code with an answer from webhook if a user is found
- 404 HTTP-code if the user ID is not found
Send user attributes for personalization.

The user ID must be unique for every user.

Open your project in Publisher Account.
In the side bar click Site Builder.
Click Open Site Builder.
Go to the Login Settings block.

Select the User ID option.

Widget customization settings in the login project do not affect the user ID authentication interface.

In the drop-down list, select New Login.

Enter the URL to receive webhooks.

Webhook URLs should start with https://. Using http:// will cause an error.

Xsolla storage is used by default. We recommend that you do not change it in Publisher Account since Xsolla storage provides a wider variety of settings.

Set up authorization via social networks already connected to your application (optional):
1. Open your project in Publisher Account and go to the Login section.
2. Click Configure in the site bar.
3. Go to the Authentication block and select Social login.

1. To set up a social network, go to the social network card, click the ⚙ icon to the right of the title, and select Connect.

To use social network authorization, in the social network card settings, specify the Application ID and secret of the application in your project. The Application ID and secret are available from the developer account of the social provider. Detailed instructions for locating the Application ID and secret are available in the social network card settings in Publisher Account.

A deep link is a special URL that directs the user not just to the main page of an application or website but directly to a specific section, page, or action.

Deep links can be used as an additional authentication method when logging in via user ID. If the game is installed on the user’s mobile device, they will be redirected to the game via deep link to get an authorization token.

User flow

In the mobile app

An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for entering the user ID or logging in through the mobile game opens.

The user clicks the Log in via Mobile Game button.
The user is redirected to the game and then automatically back to the Web Shop as an authorized user.

In the desktop version

An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for entering the user ID or logging into the mobile version of the game using a QR code opens.

The user scans the QR code using their mobile device.
The Web Shop opens on the user's mobile device.
The user is automatically redirected to the game and then back to the Web Shop as an authenticated user.

Services interaction flow

How to set up

On the game side

In your game’s mobile app settings, register a URL scheme to open the game via deep link:
- in Android applications — in the AndroidManifest.xml file
- in iOS applications — in the Info.plist file

After registering the scheme, when the user authenticates in the Web Shop via the game, the game should open at the specified address.

Example of a URL scheme to register a game:

gamename://authorize?operationPayload=<VALUE>

gamename — the name of your game that should open on a mobile device for user authentication.
authorize — an example of an action name that should be performed after the gamename game opens. Use the action name that matches the actions in your application\’s operating system.
operationPayload=<VALUE> — an additional parameter containing information for token generation during authentication.

Examples:

Copy

Full screen

Small screen

<key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>gamename</string>
      </array>
    </dict>
  </array>

Copy

Full screen

Small screen

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="gamename" android:host="authorize" />
</intent-filter>

Implement the generation of an authorization token in JWT format using the user ID from the game.

Parameter	Type	Description
loginId	string	ID of the authorization method from the Publisher Account. Required.
settings.projectId	string	Project ID found in Publisher Account, which is specified next to the name of your project in browser address bar. The URL has the following format: `https://publisher.xsolla.com/<merchantId>/projects/<projectId>`. Required.
settings.merchantId	string	Merchant ID found in Publisher Account, specified in the Company settings > Company section or in the browser address bar on any page of the Publisher Account. The URL has the following format: `https://publisher.xsolla.com/<merchantId>/`. Required.
user.id	string	User ID in the game. Required.
user.country	string	Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla and the process of determining the country. Required. Example: US
operationPayload	string	An additional parameter containing information for token generation during authentication. Required.

Example of calling the user token generation API method using curl:

Copy

Full screen

Small screen

curl -X 'POST' \
'https://sb-user-id-service.xsolla.com/api/v1/user-id/token' \
-H 'accept: /' \
-H 'Content-Type: application/json' \
-d '{
 "loginId": "000001aa-001a-0ab0-00001-01a01a01a01a",
 "settings": {
   "projectId": 123456,
   "merchantId": 123456
 },
 "user": {
   "id": "123",
   "country": "US"
 }
 "operationPayload": "kosarb2NyrtIWaegJAH1f6P7XrBYPXYDya5coc_ZzcfiS_5o4QTUAL-CcGRC_Kv4CAtg"
}'

{token="JWT_TOKEN"}

Add a pop-up window with a notification of successful authorization (optional).
Implement the opening of the Web Shop in the browser using the obtained user token.

Example of creating a URL for opening the Web Shop in the browser for an authorized user:

https://example.com/?token={token}, if you are using a custom domain
https://example.xsolla.site/?token={token}, if you are using an Xsolla domain

{token}

Within Site Builder

First set up authentication via User ID. This is necessary so that users have an alternative way of authentication if deep link authentication is not available. For example, if the game is not installed on a user’s mobile device.

Open your project in Publisher Account and go to Site Builder.
Click Configure on the card of your Web Shop site with authentication via User ID.
Go to the Login Settings and select the User ID section.
Enable Deeplink authorization toggle.

In the Deeplink URL field enter the link for user authentication.

If you are using the Fast Login block on the site:
1. Go to the Fast Login block.
2. In the Layout section, enable the QR code toggle.

To check the authentication, click on Preview.
To publish the website, click on Publish.

A deep link is a special URL that directs the user not just to the main page of an application or website but directly to a specific section, page, or action.

Deep links allow the user to authenticate in the Web Shop through the game in one click, instead of going through the authentication process via user ID or Xsolla Login.

If the game is installed on the user’s mobile device, they will be redirected to the game via deep link to get an authorization token.

When a deep link is used as the primary authentication method, it allows saving payment details, which is not possible with authentication via user ID and deeplink. In this case, the deep link only speeds up authentication but does not add any new features.

User flow

In the mobile app

An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for logging in through the mobile game opens.

The user clicks the Log in via Mobile Game button.
The user is redirected to the game and then automatically back to the Web Shop as an authorized user.

In the desktop version

An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for logging into the mobile version of the game using a QR code opens.

The user scans the QR code using their mobile device.
The Web Shop opens on the user's mobile device.
The user is automatically redirected to the game and then back to the Web Shop as an authenticated user.

Services interaction flow

How to set up

On the game side

In your game’s mobile app settings, register a URL scheme to open the game via deep link:
- in Android applications — in the AndroidManifest.xml file
- in iOS applications — in the Info.plist file

After registering the scheme, when the user authenticates in the Web Shop via the game, the game should open at the specified address.

Example of a URL scheme to register a game:

gamename://authorize?operationPayload=<VALUE>

gamename — the name of your game that should open on a mobile device for user authentication.
authorize — an example of an action name that should be performed after the gamename game opens. Use the action name that matches the actions in your application\’s operating system.
operationPayload=<VALUE> — an additional parameter containing information for token generation during authentication.

Examples:

Copy

Full screen

Small screen

<key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>gamename</string>
      </array>
    </dict>
  </array>

Copy

Full screen

Small screen

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="gamename" android:host="authorize" />
</intent-filter>

Implement the generation of an authorization token in JWT format using the user ID from the game.

Before calling the POST method https://sb-user-id-service.xsolla.com/api/v1/user-id/token make sure that authentication has been completed.

If the authentication header is not provided, saving payment methods and purchasing subscriptions will not be possible.

Authorization: Basic

your_authorization_basic_key

client_id:client_secret

documentation

Parameter	Type	Description
loginId	string	ID of the authorization method from the Publisher Account. Required.
settings.projectId	string	Project ID found in Publisher Account, which is specified next to the name of your project in browser address bar. The URL has the following format: `https://publisher.xsolla.com/<merchantId>/projects/<projectId>`. Required.
settings.merchantId	string	Merchant ID found in Publisher Account, specified in the Company settings > Company section or in the browser address bar on any page of the Publisher Account. The URL has the following format: `https://publisher.xsolla.com/<merchantId>/`. Required.
user.id	string	User ID in the game. Required.
user.country	string	Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla and the process of determining the country. Required. Example: US
operationPayload	string	An additional parameter containing information for token generation during authentication. Required.

Before generating an authorization token for the first time, you must contact your project’s personal manager or email csm@xsolla.com to activate the token configuration. This step is necessary to ensure the proper functioning of the secure user authentication method.

Example of calling the user token generation API method using curl:

Copy

Full screen

Small screen

curl -X 'POST' \
'https://sb-user-id-service.xsolla.com/api/v1/user-id/token' \
-H 'Accept: /' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <Base64Encoded(client_id:client_secret)>' \
-d '{
 "loginId": "000001aa-001a-0ab0-00001-01a01a01a01a",
 "settings": {
   "projectId": 123456,
   "merchantId": 123456
 },
 "user": {
   "id": "123",
   "country": "US"
 }
 "operationPayload": "kosarb2NyrtIWaegJAH1f6P7XrBYPXYDya5coc_ZzcfiS_5o4QTUAL-CcGRC_Kv4CAtg"
}'

{token="JWT_TOKEN"}

Add a pop-up window with a notification of successful authorization (optional).
Implement the opening of the Web Shop in the browser using the obtained user token.

Example of creating a URL for opening the Web Shop in the browser for an authorized user:

https://example.com/?token={token}, if you are using a custom domain
https://example.xsolla.site/?token={token}, if you are using an Xsolla domain

{token}

Within Site Builder

Open your project in Publisher Account and go to Site Builder.
Click Configure on your Web Shop site card.
Go to the Login Settings and select the Deep link section.

In the Deeplink URL field enter the link for user authentication.

If you are using the Fast Login block on the site:
1. Go to the Fast Login block.
2. In the Block Settings, adjust the display style for the QR code login button.

To check the authentication, click on Preview.
To publish the website, click on Publish.

User flow

The user goes to Web Shop with Xsolla Login authentication configured.
The user clicks the buy button for the selected item, the login button on the top bar, or the login button in the Fast Login block.
A modal window opens with authorization methods set up in Xsolla Login.

The user proceeds to authorization and enters additional data if necessary.
The system checks if the user exists in the game. If the user exists in the game, the user is authorized in Web Shop. Otherwise an error message is displayed.

How to get it

In the Builder for your site, go to the Login settings block.

Select the Xsolla Login authorization option.
In the drop-down list, select New Login.

As a result, the Login project with user authentication by email and password will be automatically created. For the created Login project, the Web Shop URL will be specified as a callback URL that the user will be redirected to in the following cases:

after successful authentication
after successful email confirmation
after password reset
in case of authentication failure

When you change the domain of Web Shop, the callback URL in the Login project settings changes automatically.

Go to the Login project settings from the modal window or click Set up authentication method in the Xsolla Login block.

For authentication in Web Shop, set up the same social networks as for authentication in your application. If social networks are not set up, user authentication by email address and password will be available.

When setting up the authentication in Web Shop via social networks, use the same Application ID and Application Secret as for authentication in your application.

Connect user data storage.

Depending on the method of storing user data, different product functionality is available to you (see Comparison of user data storage options).

Xsolla storage

If you want the Login product to process all authentication logic, connect to Xsolla storage. More flexible settings will be available to you.

When you create a Login project, Xsolla storage is connected by default, no additional steps are required to configure it. If you have changed the default storage type and need to reconnect to Xsolla storage, follow these steps:

Go to the User database block and select the Storage section.
Select Xsolla storage and click Save changes.

Xsolla storage supports JWT standard-based and OAuth 2.0 protocol-based authentication. All user information is stored on Xsolla’s side.

PlayFab storage

If you want to use PlayFab functionality to work with users, connect to PlayFab storage. The storage saves the following user data:

username
user email address
user password
fields from an extended registration form if the form is set up

PlayFab storage supports JWT standard-based and OAuth 2.0 protocol-based authentication.

PlayFab storage gives you access to the following features:

user registration
authentication by email address or username and password
authentication via Twitch
user password reset
user blocking

To connect the storage:

Go to the User database block and select the Storage section.
Select PlayFab.
In the Title ID field, enter the value of the same field from your PlayFab account.
Click Save changes.

All user information is stored on Xsolla’s side. User passwords are verified by PlayFab only.

Firebase storage

If you want to use Firebase functionality to work with users, connect to Firebase storage. This storage saves the following user data:

username
user email address
user password
fields from an extended registration form if the form is set up

Firebase storage supports JWT standard-based and OAuth 2.0 protocol-based authentication.

To connect the storage:

Go to the User database block and select the Storage section.
Select Firebase.
In the API key field, enter the value of the same field from your Firebase account.
Click Save changes.

All user information is stored in the JSON format and is updated in real time with every connected client.

Custom storage

If you use your own authorization system and store user data on your application side, connect to custom storage.

The custom storage gives you access to the following features:

user registration
authentication by email address or username and password
passwordless authentication by phone number
authentication via social networks
user password reset

Custom storage supports JWT standard-based authentication.

To set up the connection between the Xsolla Login server and your application as a client:

Connect the custom storage.
Set up the processing of requests from the Xsolla Login server.

All user information is stored on Xsolla’s side. User passwords are verified by the custom storage only.

Connect custom storage

Go to the User database block and select the Storage section.
Select Custom storage.
Enter URLs where to send API requests:
Click Save changes.
For the URLs you have set, implement an API that will respond as follows:
- HTTP 200 / HTTP 204 for successful requests. If required, a JSON containing additional user data can be placed in the response body. The passed data is written to a JWT (the partner_data parameter).
- Other HTTP status codes for unsuccessful requests.

If you want the JWT to contain the user ID from your database, contact your Customer Success Manager or email to csm@xsolla.com.
For passwordless authentication via a phone number to work correctly, your API response must contain the account_id parameter that matches the user ID from the client.

Set up processing of requests from Xsolla Login server

Xsolla Login server requests are sent to URLs, you specified in Publisher Account, with the Authorization: Bearer <JWT> header. The JWT is signed with the secret key of your project.

To process a request:

Validate a received JWT.
If the validation is successful, decode the JWT and make sure it includes the claims from the table below. Find and use a library for decoding.

Claim	Type	Description
exp	Unix Timestamp	The date and time of the JWT expiry. The JWT lifetime is 7 minutes.
iat	Unix Timestamp	The date and time JWT is issued.
iss	string	The service that signed the JWT: `https://login.xsolla.com`.
request_type	string	Constant: `gateway_request`.
xsolla_login_project_id	string (UUID)	Your Login project ID in Publisher Account.
social_access_token	string (UUID)	Access token of the social network through which the user was authenticated. To enable the transmission of this claim, contact your Customer Success Manager or email to csm@xsolla.com.

Example of a token payload:

Copy

Full screen

Small screen

{
  "exp": 1573635020,
  "iat": 1573634600,
  "iss": "https://login.xsolla.com",
  "request_type": "gateway_request",
  "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000"
}

Set up Fast Login block

The Fast Login block provides users with an additional way to authenticate on the site.

The appearance of the block and its features depend on the selected authentication method.

If authentication via user ID is configured for the site, the Fast Login block displays a field for entering the ID and a login button.

Features:

User authentication without additional transition to the modal window.
Setting up the content of the block. You can enable and configure the following sections:
- Title
- Description
- Instructions on how to find the user ID
- Custom background

You can also expand the features of the block, for example, add text, a button, or an image, using JS code.

If authentication via Xsolla Login is configured for the site, an additional button calling for authorization is displayed in the Fast Login block. When you click on the button in the block, a modal window opens for authorization using one of the Xsolla Login methods.

Features:

Setting up the text of the button calling for authorization
Setting up a custom background

You can also expand the features of the block, for example, add text, a button, or an image, using JS code.

For new sites, the Fast Login block is added to Web Shop template by default, and you can remove it if necessary.

If you created a site earlier and it doesn’t have a Fast Login block, you can add it.

To add a Fast Login block:

Open the project in Publisher Account.
In the side menu, click Site Builder.
In the Sites section, select your site and click Open Site Builder.
Click Add block.
Choose Fast Login block.

To use the Fast Login block, an authorization option should be chosen in advance from the drop-down list in the Login settings section.

For the user ID authentication method in the Login settings section, you also need to specify the URL to receive the webhook. If you don’t specify it, the site can’t be published because user authentication will be unavailable.

User authentication during site preview is possible without adding a webhook URL.

Next steps

Useful links

Integration flow

Thank you for your feedback!

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

Last updated: April 2, 2025

Found a typo or other text error? Select the text and press Ctrl+Enter.

Contents

User flow
How to get it
User flow
In the mobile app
In the desktop version
Services interaction flow
How to set up
On the game side
Within Site Builder
User flow
In the mobile app
In the desktop version
Services interaction flow
How to set up
On the game side
Within Site Builder
User flow
How to get it
Xsolla storage
PlayFab storage
Firebase storage
Custom storage
Connect custom storage
Set up processing of requests from Xsolla Login server
Set up Fast Login block
Next steps
Useful links

Your browser is not supported. Please try a different browser

Set up user authentication

User flow

How to get it

User flow

In the mobile app

In the desktop version

Services interaction flow

How to set up

On the game side

loginId

settings.projectId

settings.merchantId

user.id

user.country

operationPayload

Within Site Builder

User flow

In the mobile app

In the desktop version

Services interaction flow

How to set up

On the game side

loginId

settings.projectId

settings.merchantId

user.id

user.country

operationPayload

Within Site Builder

User flow

How to get it

Xsolla storage

PlayFab storage

Firebase storage

Custom storage

Connect custom storage

Set up processing of requests from Xsolla Login server

Set up Fast Login block

Next steps

Useful links