• Version: 1.0.0
• Servers: https://login.xsolla.com/api
• Protocols: https
• Accepts: application/json
• Responds with: application/json
• Contact us by email
• Contact URL: https://xsolla.com/

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

You can download the API definition in two formats:

• YAML
• JSON

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.

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

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

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:

• User token. It is used for sending requests to the following user resources:
  • profile
  • friends
  • attributes
• Server token. It is used for sending requests to application resources such as settings or user data. The following requests are available:
  • Create platform accounts
  • Get user data
  • Link accounts
  • Link user accounts via external ID

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

• user registration (JWT or OAuth 2.0)
• authentication by username and password (JWT, OAuth 2.0, or JWT auth by username and password)
• authentication via social networks (JWT or OAuth 2.0)
• silent authentication (JWT or OAuth 2.0)
• authentication via a social network access token
• authentication via a publishing platform

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:

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.

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: 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.

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.

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.

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: 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.

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.

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"
  }
}