Overview
This section describes methods for working with Login. Set up your Login project in Publisher Account before sending requests.
Glossary
You have access to the following Login project types in Publisher Account:
- Standard Login project
- Shadow Login project
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:
- 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:
Getting a user token
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
).
Getting a server token
Using a server token requires an OAuth 2.0 client. Contact your Account Manager to create it.
To get a token, send a Generate JWT request with the grant_type=client_credentials
parameter.
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 method.
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 method.
Claim | Type | Description |
---|---|---|
exp |
Unix Timestamp | Date and time of token expiration. Default expiration time is 24 hours. You can change expiration time for every Login project. Required. |
iss |
string | Service that signed the token: https://login.xsolla.com . Required. |
iat |
Unix Timestamp | Date and time of giving the token. Required. |
sub |
string (UUID) | User ID written on the Xsolla Login server side. Required. |
groups |
array | 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. |
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. |
xsolla_login_project_id |
string (UUID) | Login project ID. Required. |
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. |
PlayFab storage
Claims that are contained in the token after authentication if you use PlayFab storage.
Claim | Type | Description |
---|---|---|
external_account_id |
string | User PlayFab ID. Required. |
session_ticket |
string | 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 | An EntityToken.EntityToken parameter. Required. |
entity_type |
string | An EntityToken.Entity.Type parameter. Can have only the title_player_account value. Required. |
entity_id |
string | An EntityToken.Entity.Id parameter. Required. |
Custom storage
Claims that are contained in the token after authentication if you use custom storage.
Claim | Type | Description |
---|---|---|
external_account_id |
string | User ID on your server side. |
provider |
string | Name of a social network used for authentication. If the user authenticates via username and password, the claim has the xsolla value. Required. |
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 | Description |
---|---|---|
provider |
string | Name of a social network used for authentication. Required. |
id |
string | User ID in a social network. Required. |
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 | Description |
---|---|---|
jti |
string | Unique token ID. Required. |
Authentication via a phone number
Claim which is contained in the token after authentication via a phone number.
Claim | Type | Description |
---|---|---|
phone_number |
string | User’s phone number used for authentication. The phone number format based on the country code, area code, and line number without any dividers. Required. |
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 methods with server-based authentication for these resources.
Claim | Type | Description |
---|---|---|
xsolla_login_project_id |
string (UUID) | ID of a Login project that owns the OAuth 2.0 client. Required. |
resources |
array | List of resources owned by a OAuth 2.0 client. Possible types of resources:
Every group is written in the following format:
|
jti |
string | Unique token ID. Required. |
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:
- Choose the library and connect it on the server side of your application.
- Copy the secret key value from Publisher Account > your Login project > General settings > Secret key.
- Pass the secret key value to the validation function entry.
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) Invalid request parameters
Code | Description |
---|---|
0 | Your request has invalid parameters. |
010-019 | Client authentication failed (e.g. unknown client, no client authentication included, or unsupported authentication method). |
010-022 | The state is missing or has less than 8 characters, and is, therefore, considered too weak. |
010-023 | The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued for another client. |
401 (Unauthorized) Incorrect authorization data
Code | Description |
---|---|
002-016 | Invalid token. |
002-040 | Unable to authorize a banned user. |
003-001 | Wrong username or password. |
003-007 | User account is not confirmed. |
003-025 | An error occurred while getting an OAuth 2.0 request token. |
003-040 | The user is unauthorized. |
010-026 | The resource owner or the authorization server denied the request. |
403 Authentication token is invalid
Code | Description |
---|---|
1901-0001 | Invalid token. |
404 (Not Found) Requested resource 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) Semantic errors in request
Code | Description |
---|---|
0 | Nickname missed in the query. |
002-050 | User’s two-factor authentication settings have not changed. |
003-003 | A user with the specified username already exists. |
003-020 | This method is unavailable for this Login project. |
003-022 | This Login project is misconfigured. You have to change Login settings in Xsolla Publisher Account or contact your Account Manager. |
003-033 | Mismatch project type. |
006-003 | Only clients with “client_credentials” grant type may have an access list. |
010-015 | Social network authentication failed: Steam. |
010-016 | This social account is already linked to another user. |
010-032 | Social network is not enabled for this Login. You can enable it in your Xsolla Publisher Account > Login Project > Social connections. |
030-024 | Reset password is disabled for this Login project. |
2002-0001 | Attributes are duplicated. |
429 (Too Many Requests) Too many requests are sent during the rate limit period
Code | Description |
---|---|
002-054 | The allowed number of searches exceeded. Wait one second before the next request. |
010-005 | Allowable number of requests exceeded. |
1900-0001 | Allowable number of requests exceeded. |