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:
  • Create platform accounts
  • Get user data
  • Link accounts
  • Link user accounts via external ID
  • Manage OAuth 2.0 clients:
    • Get list of project clients
    • Create client
    • Update client settings

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.

PlayFab Storage

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

Custom Storage

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

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.

Authentication via the OAuth 2.0 Protocol

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

Authentication by a Phone Number

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

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.

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.

Errors

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

{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 (Bad Request) Invalid request parameters

401 (Unauthorized) Incorrect authorization data

403 Authentication token is invalid

404 (Not Found) Requested resource not found

418 I’m a teapot

422 (Unprocessable Entity) Semantic errors in request

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