Login API
Login API
All APIs
Documentation
Create Account
No results found.
Getting Started
Overview
Authentication
JWT Structure
JWT Validation
Glossary
Errors
Attributes
Project
Users
JWT
OAuth 2.0
General

Overview

This section describes methods for working with Login. Please set up your Login project in Publisher Account before sending requests.

Authentication

Login API supports the following token types:

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

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:

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

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 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 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 playfab value to the scope 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 object Data 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.
scp array List of the scope parameter values. 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:

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

  1. Choose the library and connect it on the server side of your application.
  2. Copy the secret key value from Publisher Account > your Login project > General settings > Secret key.
  3. Pass the secret key value to the validation function entry.
Notice: Do not reveal your secret key to anyone. If it was compromised, please update it.

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

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 bad 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
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.
030-024 Reset password is disabled for this Login.
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.
2002-0001 Attributes are duplicated.

429 (Too Many Requests) Too many requests are sent during the rate limit period

Code Description
010-005 Allowable number of requests exceeded.
1900-0001 Allowable number of requests exceeded.