Xsolla-logo

Overview

This section describes API calls for working with Login. Set up your Login project in Publisher Account before sending requests.

IP addresses

The full list of IP addresses that login.xsolla.com may use:

  • 34.94.0.85
  • 34.94.14.95
  • 34.94.25.33
  • 34.94.115.185
  • 34.94.154.26
  • 34.94.173.132
  • 34.102.48.30
  • 35.235.99.248
  • 35.236.32.131
  • 35.236.35.100
  • 35.236.117.164

Download API definition

You can download the API definition in two formats:

Glossary

You have access to the following Login project types in Publisher Account:

  • Standard Login project
  • Shadow Login project

To find more information on it, see Cross-platform account feature.

Rate limits

Are the restrictions applied by Xsolla API on the frequency of access by a user within a defined timeframe.

Standard Login project

Is a Login project that is used to store main accounts.

Shadow Login project

Is a Login project that is used to store platform accounts.

Main account

Is an account type that is created in a standard Login project and linked to platform accounts. The main account is used to identify the player on different platforms.

Platform account

Is an account type that is created in a shadow Login project and connected to a definite publishing platform. The platform account can’t be linked to another platform account. Also, you can’t unlink the accounts from a main account.

Publishing platform

Is a game platform that is used for game distribution (e.g. Steam, PlayStation, Xbox, etc.).

Authentication

Login API supports the following token types:

Authentication schemes

You can determine whether an API call is client or server-side by the scheme of authentication:

  • Client-side — are called without authentication or with the Authorization header: Bearer <user_JWT> header, where <user_JWT> — is the user token.
  • Server-side API calls for implementing the user flow — are called with the header: X-SERVER-AUTHORIZATION: <server_JWT>, where <server_JWT> — is the server token.

Getting a user token

To get the token, send one of the following requests:

After JWT authentication, the user is redirected to the Callback URL with a token in a query-parameter: <Callback URL>?token=<User token (JWT)>.

After OAuth 2.0 protocol-based authentication, send the Generate JWT request to the Xsolla Login server to exchange the received code parameter for a user token (access_token).

Getting a server token

To get a server token:

  1. Set up server OAuth 2.0 client.
  2. Generate server JWT.

Set up server OAuth 2.0 client

  1. Open your project in Publisher Account and go to the Login section.
  2. Click Configure in the panel of a Login project.
  3. Go to the Security block and select the OAuth 2.0 section.
  4. Click Add OAuth 2.0 Client.
  5. Check the Server (server-to-server connection) box.
  6. Specify Token lifetime.
  7. Click Connect.
  8. Copy and save the client ID and secret key.

Generate server JWT

On the back end of your application, implement a method to get the server JWT using the Generate JWT API call. The request must contain the following parameters:

  • grant_type is the type of getting JWT, pass the client_credentials value.
  • client_secret is the secret key that is received when you set up the server OAuth 2.0 client.
  • client_id is the client ID received when you set up the server OAuth 2.0 client.

Rate limits

To prevent Xsolla system overloads and protect against sudden spikes in incoming traffic, Xsolla limits the number of requests received by the Xsolla API within a specified period of time. If the limit is exceeded, the Xsolla API returns an HTTP response with the 429 status code.

Rate limits vary by method, IP-address, authentication scheme, and other factors.

Rate limits for server-side methods are applied to methods with server-side authentication — methods that are called with the X-SERVER-AUTHORIZATION: <server_JWT> header, where <server_JWT> is the server token.

Rate limits for client-side methods are applied to methods without authentication or with client-side authentication — methods that are called with the Authorization: Bearer <user_JWT> header, where <user_JWT> is the user token.

Example of a method with server-side authentication: Example of a method with server-side authentication Example of a method with client-side authentication: Example of a method with server-side authentication

Rate limits for client-side methods do not change and are necessary to prevent brute-force attacks. The maximum request rate for server-side methods is higher than for client-side methods. You can refer to the recommendations on how to manage rate limits in the documentation.

Note In certain cases, it is possible to adjust the rate limits by request. To request the rate limits adjustment, contact your Customer Success Manager or email csm@xsolla.com.

JWT structure

Every token has a JWT format and contains a definite information in a payload.

User JWT

User JWT is a token received as a result of authentication or registration. A token payload contains information about the user and authentication call.

Getting a user token via the OAuth 2.0 protocol requires an OAuth 2.0 client. The user token is passed in the Authorization: Bearer <JWT> header.

Main claims

A token will contain the main claims after authentication or email address confirmation. Presence of these claims does not depend on the user database and authentication call.

 
Claim Type Required Description
exp Unix Timestamp Yes Date and time of token expiration. Default expiration time is 24 hours. You can change expiration time for every Login project.
iss string Yes Service that signed the token: https://login.xsolla.com.
iat Unix Timestamp Yes Date and time of giving the token.
sub string (UUID) Yes User ID written on the Xsolla Login server side.
groups array Yes

The list of groups the user is in. Every group is written in the following format:

  • id — group ID
  • name — group name
  • is_default — shows whether the group is default or not (true or false values).

There can be only one default group. This group initially includes all users before they are distributed into different groups.

xsolla_login_project_id string (UUID) Yes Login project ID.
type string

Authentication option:

  • xsolla_login — login via username/email and password.
  • social — social login
  • email — passwordless login via one-time code received by email.
  • phone — passwordless login via one-time code received by SMS.
  • firebase — login via username/email and password when the user data storage is Firebase.
  • playfab — login via username/email and password when the user data storage is PlayFab.
  • proxy — login via username/email and password when the user data storage is custom.
  • device — login with device ID.
  • server_custom_id — login with custom ID.

There can be only one default group. This group initially includes all users before they are distributed into different groups.

avatar string User avatar URL.
username string Username.
publisher_id integer ID of a merchant who owns a Login project.
email string User email address.
payload string Additional information that is passed in the payload parameter during authentication.
promo_email_agreement boolean

May have one of the following values:

  • true if the user agrees to receive a newsletter.
  • false otherwise.
Has the true value by default.

To add the feature to the registration form of the Login widget:

  • Contact your Account Manager if you use Widget 2.0.
  • Add the fields parameter with the promo_email_agreement value to the initialization code if you use the previous version of the widget.

connection_information string Shows whether the user confirmed their birth date or not. Confirmation is made via the okname service.

PlayFab storage

Claims that are contained in the token after authentication if you use PlayFab storage.

Claim Type Required Description
external_account_id string Yes User PlayFab ID.
session_ticket string Yes

A SessionTicket parameter received during an authentication request or requests to the PlayFab API.

A token contains the claim if you authenticate users via the OAuth 2.0 protocol and pass the playfab value to the scope parameter.

entity_token string Yes An EntityToken.EntityToken parameter.
entity_type string Yes An EntityToken.Entity.Type parameter. Can have only the title_player_account value.
entity_id string Yes An EntityToken.Entity.Id parameter.

Custom storage

Claims that are contained in the token after authentication if you use custom storage.

Claim Type Required Description
provider string Yes Name of a social network used for authentication. If the user authenticates via username and password, the claim has the xsolla value.
external_account_id string User ID on your server side.
partner_data Data of any type returned by your server in the response body during authentication.

Social authentication

Claims that are contained in the token after authentication via a social network. Presence of these claims does not depend on the user database.

Claim Type Required Description
provider string Yes Name of a social network used for authentication.
id string Yes User ID in a social network.
is_cross_auth boolean Shows that the silent authentication request is in progress.
social_access_token string Social network account access_token parameter used for authentication. Contact your Account Manager to set up the feature.
picture string (URL) Link to the user profile picture in a social network.
birthday date (RFC3339) User birth date in a social network.
gender string User gender in a social network.
name string User nickname in a social network.

Authentication via the OAuth 2.0 protocol

Claims that are contained in the token after OAuth 2.0 authentication.

Claim Type Required Description
jti string Yes Unique token ID.

Authentication via a phone number

Claim which is contained in the token after authentication via a phone number.

Claim Type Required Description
phone_number string Yes User's phone number used for authentication. The phone number format based on the country code, area code, and line number without any dividers.

Server JWT

The server token is passed in the X-SERVER-AUTHORIZATION header.

The token payload contains information about resources owned by the OAuth 2.0 client. The token has access to calls with server-based authentication for these resources.

Claim Type Required Description
xsolla_login_project_id string (UUID) Yes ID of a Login project that owns the OAuth 2.0 client.
resources array Yes

List of resources owned by a OAuth 2.0 client. Possible types of resources:

  • publisher_id — resources of a merchant who owns the Login project
  • publisher_project_id — resources of a project in Publisher Account.

Every group is written in the following format:

  • name — resource type
  • value — resource ID

jti string Yes Unique token ID.

JWT validation

After successful authentication, every user has a JWT generated for them. Generated JWT is signed by a secret key. To make sure that a JWT is relevant and belongs to the user of your Login project, you should validate its value.

To validate a JWT:

  1. Open your project in Publisher Account and go to the Login section.
  2. Click Configure in the panel of a Login option.
  3. On the navigation page, go to the Security block and select the JWT Signature section.
  4. Select your encryption method and copy the value of the Secret key or New public JSON Web Key field, depending on the selected method.
  5. Choose the library and connect it on the server side of your application.
  6. Pass the value, copied in the step 4, to the validation function entry.

Notice

Do not reveal your secret key to anyone. If it was compromised, please update it.

Errors

In case of error responses the Xsolla Login server returns a JSON object with the following fields:

Field Type Description
code string Xsolla Login server error code.
description string Error description. The text is always in English. Do not use this text in case of an error, as the value can change in the future.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 Bad Request

Code Description
0 Request has invalid parameters.
010-019 Client authentication failed (e.g. unknown client, no client authentication included, or unsupported authentication method).
010-022 Parameter state missing or too weak as it has less than 8 characters.
010-023 Authorization grant or refresh token is invalid, expired, revoked, doesn’t match the redirection URI used in authorization request, or issued for another client.

401 Unauthorized

Code Description
002-016 Invalid token.
002-040 Unable to authorize banned user.
003-001 Wrong username or password.
003-007 User account not confirmed.
003-025 Error occurred while getting OAuth 2.0 access token.
003-040 Unauthorized user.
010-026 Xsolla Login server or resource owner denied request.

403 Forbidden

Code Description
1901-0001 Invalid token.

404 Not Found

Code Description
003-002 User not found.
003-019 Project not found.
003-061 Object not found.

418 I’m a teapot

Code Description
004-001 Something went wrong.

422 Unprocessable Entity

Code Description
0 Nickname missed in query.
002-050 User’s two-factor authentication settings not changed.
003-003 User with specified username already exists.
003-020 Call unavailable for this Login project.
003-022 This Login project misconfigured. Change this Login project settings in Xsolla Publisher Account or contact your Account Manager.
003-033 Mismatch project type.
006-003 OAuth 2.0 clients with client_credentials grant type only can have access list.
010-015 Social network authentication failed: SERVICE_NAME.
010-016 This social account already linked to another user.
010-032 Authentication via this social network not enabled for this Login project. Enable it in your Xsolla Publisher Account > Login > your Login project > Social connections.
030-024 Password reset disabled for this Login project.
2002-0001 Duplicated attributes.

429 Too Many Requests

Code Description
002-054 Allowed number of search attempts exceeded. Wait one second before next request.
010-005 Allowed number of requests exceeded.
1900-0001 Allowed number of requests exceeded.