https://login.xsolla.com/api
This section describes API calls for working with Login. Set up your Login project in Publisher Account before sending requests.
The full list of IP addresses that login.xsolla.com may use:
You have access to the following Login project types in Publisher Account:
To find more information on it, see Cross-platform account feature.
Are the restrictions applied by Xsolla API on the frequency of access by a user within a defined timeframe.
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.
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.
Is a game platform that is used for game distribution (e.g. Steam, PlayStation, Xbox, etc.).
Login API supports the following token types:
You can determine whether an API call is client or server-side by the scheme of authentication:
Authorization
header: Bearer <user_JWT>
header, where <user_JWT>
— is the user token.X-SERVER-AUTHORIZATION: <server_JWT>
, where <server_JWT>
— is the server 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
).
To get a server token:
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.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 client-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.
Every token has a JWT format and contains a definite information in a payload.
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.
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:
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:
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 value by default.
To add the feature to the registration form of the Login widget:
|
|
connection_information |
string | Shows whether the user confirmed their birth date or not. Confirmation is made via the okname service. |
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 |
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. |
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. To enable the transmission of this claim, contact your Customer Success Manager or email to csm@xsolla.com | ||
social_access_token |
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. |
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. |
Claims that are contained in the token after OAuth 2.0 authentication.
Claim | Type | Required | Description |
jti |
string | Yes | Unique token ID. |
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. |
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:
Every group is written in the following format:
|
jti |
string | Yes | Unique token ID. |
To validate the JWT, use the following Login API calls:
Notice
Do not reveal your secret key to anyone. If it was compromised, please update it.
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"
}
}
Error Code | Description | Recommendation |
---|---|---|
002-016 | The user should try to log in again. | |
002-027 | Make sure all request parameters are correct. | |
002-028 | Make sure all required parameters are provided. | |
002-040 | The user should contact the game support team. | |
002-043 | The user should try another phone number that can receive SMS. | |
002-050 | The error occurs when trying to enable two-factor authentication if it's already enabled, or disable it if it's already disabled. | |
002-056 | The user should verify the phone number or enter a different one. | |
002-057 | The user should try again later. If you believe this error should not occur, please contact the integrator team in any messenger. | |
002-058 | The user should use the link in the email to unblock their account or reset the password. | |
002-060 | Inform the user of the age restrictions. | |
003-001 | The user should verify the entered information and try again. | |
003-002 | The user should sign up in the game to continue. | |
003-003 | The user should try a different username. | |
003-004 | The user should use a different email address. | |
003-005 | The user should try a different email address. | |
003-007 | The user should confirm their email address to activate the account. If they haven't received a confirmation email, they should check the spam folder. | |
003-008 | Changing the email address is not allowed. | |
003-009 | The search failed for technical reasons, please try again later. | |
003-010 | Changing the birth date is not allowed. | |
003-011 | The user should confirm the email address or use another one that has not been previously used during registration. | |
003-012 | The user should confirm the phone number or use another one that has not been previously used during registration. | |
003-019 | Check the existence of the authentication variant with the passed ID. | |
003-020 | Check the authorization option settings in your Publisher Account. | |
003-021 | The user should contact game support. | |
003-022 | Verify the authorization option settings in your Publisher Account. | |
003-023 | Registration is not allowed for this authorization option. The user should contact game support. | |
003-030 | The password reset link has expired or is incorrect. The user should attempt to reset the password again. | |
003-049 | The user should try again later. | |
007-001 | The user should use an alternative login method. | |
008-001 | Add the correct login URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | |
008-002 | Add the correct user verification URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | |
008-003 | Add the correct URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | |
008-004 | Add the correct password reset URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | |
008-005 | Ensure the correct Title ID is specified in the authorization option settings in your Publisher Account (section User database > Storage). | |
008-006 | Ensure the PlayFab API key is valid. | |
008-008 | Ensure the server returns the accountID parameter in the response body. |
|
008-009 | Verify the URLs specified in the Custom storage settings in the authorization option in your Publisher Account (section User database > Storage > Custom storage). | |
008-011 | Ensure that the callback URL for password reset is specified in the authorization option settings in your Publisher Account (section Password settings). | |
008-013 | Ensure that a link to the user agreement is specified in the authorization option settings in your Publisher Account (section Legal Terms > Policies and Agreements). | |
008-014 | Contact the integration team through any messenger. | |
008-015 | Contact the integration team through any messenger. | |
008-016 | Add the API key to the settings in your Publisher Account (section Legal Terms > Policies and Agreements). | |
010-004 | The user should try again later. | |
010-005 | The user should try again later. | |
010-006 | The user should add another authentication method before unlinking the social network. | |
010-007 | The user should complete the CAPTCHA again. | |
010-010 | The user should verify the code and try again. | |
010-014 | The user should log in again from the login page. | |
010-015 | The user should try again later. | |
010-016 | The user should use a different social account. If they believe this is an error, they should contact the integration team through any messenger. | |
010-017 | Verify the correctness of the request parameters being sent. | |
010-019 | Ensure that a client with the provided client_id exists. |
|
010-020 | Ensure that the provided scope parameter is correct. Refer to the instructions for detailed setup information. |
|
010-021 | Ensure that the value of the response_type parameter is set to "code" . |
|
010-022 | Ensure that the state parameter is present and consists of at least 8 characters. | |
010-023 | Ensure that the authorization code is valid and not expired, and that the redirect_uri parameter contains an authorized URL. Refer to the instructions for detailed setup information. |
|
010-026 | Ensure that you have sufficient permissions to access the resource. | |
010-030 | Ensure that cross-authentication is enabled for the authorization option. Refer to the instructions for detailed setup information. | |
010-031 | The error occurs when attempting to connect a social network that is already enabled. | |
010-032 | Ensure that the social network is enabled and configured in the authorization option settings in your Publisher Account (section Authorization via Social Networks). | |
010-033 | The user should try again later. | |
010-035 | The user should try again later. | |
010-045 | The user should use a different social account for registration. | |
030-024 | The user should contact the game support team. | |
040-001 | The user should enter an email address containing no more than 254 characters. | |
040-002 | The user should enter a valid email address. | |
040-003 | The user should enter a different email address. | |
040-004 | The user should contact Xsolla support. | |
040-005 | The user should enter an email with only one @ character. |
|
040-006, 040-007, 040-008 | The user should contact Xsolla support. | |
040-009 | The user should enter an email with an existing domain. | |
040-010 | The user should contact Xsolla support. | |
010-018 | The user should enter a different email address. | |
300-003 | The user should try again later. | |
300-005 | The user should try again later. | |
300-006 | The user should verify and re-enter the confirmation code. | |
300-008 | The user should use the new code sent to their email or phone. | |
003-007 | The user should confirm their email address to activate the account. If they haven't received a confirmation email, they should check the spam folder. | |
003-025 | The user should try a different authentication method. | |
003-040 | The user should log in again. | |
003-033 | Ensure that shadow authentication is used for the authorization option. | |
2002-0001 | Make sure that the attribute being created has not been previously added to the user. |