Skip to content
/
[OAuth2.0] Start auth by...

Login API (v1)

Overview

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

IP addresses

The full list of IP addresses that login.xsolla.com may use:

  • 34.94.0.85
  • 34.94.14.95
  • 34.94.25.33
  • 34.94.115.185
  • 34.94.154.26
  • 34.94.173.132
  • 34.102.48.30
  • 35.235.99.248
  • 35.236.32.131
  • 35.236.35.100
  • 35.236.117.164

Glossary

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.

Rate limits

Are the restrictions applied by Xsolla API on the frequency of access by a user within a defined timeframe.

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:

Authentication schemes

You can determine whether an API call is client or server-side by the scheme of authentication:

  • Client-side — are called without authentication or with the Authorization header: Bearer <user_JWT> header, where <user_JWT> — is the user token.
  • Server-side API calls for implementing the user flow — are called with the header: X-SERVER-AUTHORIZATION: <server_JWT>, where <server_JWT> — is the server token.

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 POST request to the Xsolla Login server to exchange the received code parameter for a user token (access_token).

When the access token expires, the client sends Generate JWT POST request endpoint on the Xsolla Login server. The request body must include the following parameters:

  • grant_type — JWT grant type, pass the refresh_token value.
  • client_id — OAuth 2.0 client ID.
  • refresh_token — refresh token received in response to the user authorization request.

Getting a server 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.

When the server token expires, generate a new token using the Generate JWT API call. The request body must include the following parameters:

  • grant_type — JWT grant type, pass the client_credentials value.
  • client_id — OAuth 2.0 client ID.
  • client_secret — OAuth 2.0 client secret key.

Rate limits

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 server-side authentication Example of a method with client-side authentication: Example of a method with server-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.

Note

In certain cases, it is possible to adjust the rate limits by request. To request the rate limits adjustment, contact your Customer Success Manager or email csm@xsolla.com.

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

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

ClaimTypeRequiredDescription
expUnix TimestampYesDate and time of token expiration. Default expiration time is 24 hours. You can change expiration time for every Login project.
issstringYesService that signed the token: https://login.xsolla.com.
iatUnix TimestampYesDate and time of giving the token.
substring (UUID)YesUser ID written on the Xsolla Login server side.
groupsarrayYesList of groups the user is in. Each group: id — group ID; name — group name; is_default — whether the group is default (true or false). There can be only one default group, which initially includes all users before they are distributed into different groups.
xsolla_login_project_idstring (UUID)YesLogin project ID.
typestringAuthentication option: xsolla_login — login via username/email and password; social — social login; email — passwordless login via one-time code by email; phone — by SMS; firebase — Firebase storage; playfab — PlayFab storage; proxy — custom storage; device — device ID; server_custom_id — custom ID.
avatarstringUser avatar URL.
usernamestringUsername.
publisher_idintegerID of a merchant who owns a Login project.
emailstringUser email address.
payloadstringAdditional information that is passed in the payload parameter during authentication.
promo_email_agreementbooleantrue if the user agrees to receive a newsletter, false otherwise. Default: true. To add to the Login widget registration form: contact your Account Manager (Widget 2.0) or add the fields parameter with the promo_email_agreement value to the initialization code (previous widget version).
connection_informationstringShows 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.

ClaimTypeRequiredDescription
external_account_idstringYesUser PlayFab ID.
session_ticketstringYesA 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_tokenstringYesAn EntityToken.EntityToken parameter.
entity_typestringYesAn EntityToken.Entity.Type parameter. Can have only the title_player_account value.
entity_idstringYesAn EntityToken.Entity.Id parameter.

Custom storage

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

ClaimTypeRequiredDescription
providerstringYesName of a social network used for authentication. If the user authenticates via username and password, the claim has the xsolla value.
external_account_idstringUser ID on your server side.
partner_dataData 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 csm@xsolla.com.
social_access_tokenAccess 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 csm@xsolla.com.

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.

ClaimTypeRequiredDescription
providerstringYesName of a social network used for authentication.
idstringYesUser ID in a social network.
is_cross_authbooleanShows that the silent authentication request is in progress.
social_access_tokenstringSocial network account access_token parameter used for authentication. Contact your Account Manager to set up the feature.
picturestring (URL)Link to the user profile picture in a social network.
birthdaydate (RFC3339)User birth date in a social network.
genderstringUser gender in a social network.
namestringUser nickname in a social network.

Authentication via the OAuth 2.0 protocol

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

ClaimTypeRequiredDescription
jtistringYesUnique token ID.

Authentication via a phone number

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

ClaimTypeRequiredDescription
phone_numberstringYesUser's phone number used for authentication. The phone number format based on the country code, area code, and line number without any dividers.

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 calls with server-based authentication for these resources.

ClaimTypeRequiredDescription
xsolla_login_project_idstring (UUID)YesID of a Login project that owns the OAuth 2.0 client.
resourcesarrayYesList of resources owned by an OAuth 2.0 client. Possible types: publisher_id — resources of a merchant who owns the Login project; publisher_project_id — resources of a project in Publisher Account. Each resource: name — resource type; value — resource ID.
jtistringYesUnique token ID.

JWT validation

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.

Errors

Refer to the documentation for information about Xsolla Login API errors.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://xsolla.redocly.app/_mock/api/login/
https://login.xsolla.com/api/

Age restrictions

Operations

Custom email templates

Operations

RSA keys

Operations

Social

Operations

User groups

Operations

Multi-factor authentication

Operations

Webhooks

Operations

User profile

Operations

Account linking

Operations

Password reset

Operations

Social networks

Operations

User friends

Operations

User groups

Operations

Export/Import

Operations

Via server custom ID

Operations

User and server token management

Operations

Via device ID

Operations

Via social networks

Operations

Cross-platform

Operations

Classic (with password)

Operations

Passwordless

Operations

[OAuth2.0] Complete auth by phone number

Request

Completes authentication by the user phone number and a confirmation code. The code lifetime is 3 minutes.

This call is used only with the Start auth by phone number call.

The workflow of using this call:

  1. The application opens an authentication form so the user can enter their phone number.
  2. The user enters their phone number.
  3. The application sends the Start auth by phone number request to the Xsolla Login server: a. If the parameter send_link is true, after this request, you should send the Get confirmation code request to make SMS contain the confirmation code and link. b. If the parameter send_link is false or not passed, the SMS will contain the confirmation code only.
  4. The Xsolla Login server sends the SMS and returns the ID of the confirmation code.
  5. The application shows a field so the user can fill in the confirmation code.
  6. The user enters the received confirmation code or follows the link.
  7. The application sends this request to the Xsolla Login server.
  8. The user is considered as authorized.
Query
client_idintegerrequired
Bodyapplication/jsonrequired
codestringrequired

Confirmation code.

operation_idstringrequired

ID of the confirmation code.

phone_numberstring^\+(\d){5,25}$required

User phone number.

curl --request POST \
  --url 'https://login.xsolla.com/api/oauth2/login/phone/confirm?client_id=SOME_INTEGER_VALUE' \
  --data '{"code":"string","operation_id":"string","phone_number":"string"}'

Responses

OK

Bodyapplication/json
login_urlstringrequired

URL generated from the redirect_uri with additional parameters. The code parameter is the user authentication code which must be exchanged to a JWT.

Example: "http://someurl.com?token=XXXXXXX"
Response
application/json
{
  "login_url": "http://someurl.com?token=XXXXXXX"
}

[OAuth2.0] Start auth by phone number

Request

Starts authentication by the user phone number and sends a confirmation code to their phone number. The code lifetime is 3 minutes.

This call is used only with the Complete auth by phone number call.

The workflow of using this call:

  1. The application opens an authentication form so the user can enter their phone number.
  2. The user enters their phone number.
  3. The application sends this request to the Xsolla Login server: a. If the parameter send_link is true, after this request, you should send the Get confirmation code request to make SMS contain the confirmation code and link. b. If the parameter send_link is false or not passed, the SMS will contain the confirmation code only.
  4. The Xsolla Login server sends the SMS and returns the ID of the confirmation code.
  5. The application shows a field so the user can fill in the confirmation code.
  6. The user enters the received confirmation code or follows the link.
  7. The application sends the Complete auth by phone number request with the received ID to the Xsolla Login server.
  8. The user is considered as authorized.
Query
response_typestringrequired

Grant type used in your project that has the enabled OAuth 2.0 protocol. Must be code to get the user authentication code in the response. The received code must be exchanged to a JWT via the Generate JWT call to finish user authentication.

client_idintegerrequired
scopestring

Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account.

Can be:

  • offline to use refresh_token from the Generate JWT call to refresh the JWT when it is expired.
  • playfab to write SessionTicket to the session_ticket claim of the JWT if you store user data at PlayFab.

If you process your own values of the scope parameter, that are not mentioned above, you can set them when using this call. The Xsolla Login server does not process these values, but returns them in the received JWT.

statestringrequired

Value used for additional user verification. Often used to mitigate CSRF Attacks. The value will be returned in the response. Must be longer than 8 symbols.

redirect_uristring

URL to redirect the user to after account confirmation, successful authentication, or password reset confirmation. To set up this parameter, contact your Customer Success Manager or email to csm@xsolla.com. <div class="notice"><strong>Notice</strong><br> The parameter is required if you have more than one redirect URI in your project settings.</div>

Bodyapplication/jsonrequired
link_urlstring(uri)

URL to redirect the user to the status authentication page. Required if the parameter send_link is true.

phone_numberstring^\+(\d){5,25}$required

User phone number.

send_linkboolean

Shows whether a link is sent with the confirmation code in the SMS or not.

The link can be used instead of the confirmation code to log in.

If the parameter has the true value, the link is sent in the SMS.

sourcestring

to mark that request goes from Xsolla Link

Value"xsolla_link"
curl --request POST \
  --url 'https://login.xsolla.com/api/oauth2/login/phone/request?response_type=SOME_STRING_VALUE&client_id=SOME_INTEGER_VALUE&scope=SOME_STRING_VALUE&state=SOME_STRING_VALUE&redirect_uri=SOME_STRING_VALUE' \
  --data '{"link_url":"http://example.com","phone_number":"string","send_link":true,"source":"xsolla_link"}'

Responses

OK

Bodyapplication/json
operation_idstringrequired

ID of the confirmation code.

remaining_ttlinteger

Remaining time for resend. The value is in seconds.

Response
application/json
{
  "operation_id": "string",
  "remaining_ttl": 0
}

Get confirmation code

Request

Waits until the user follows the link provided via email or SMS and returns the confirmation code for authentication. If you sent this call and after 20 seconds you didn't get the code, there was an error. In this case, resend the call immediately. The code lifetime is 3 minutes.

The workflow of using this call:

  1. The application opens an authentication form so the user can enter their email address.
  2. The user enters their email address.
  3. The application sends the Start auth by email or phone number (JWT or OAuth 2.0) request to the Xsolla Login server: a. If the parameter send_link is true, after this request, you should send this same request to make email or SMS contain the confirmation code and link. b. If the parameter send_link is false or not passed, the email will contain the confirmation code only.
  4. The Xsolla Login server sends an email or SMS to the user and returns the ID of the confirmation code.
  5. The application shows a field so the user can fill in the confirmation code.
  6. The user enters the received confirmation code or follows the link.
  7. The application sends the Complete auth by email or phone number (JWT or OAuth 2.0) request with the received ID to the Xsolla Login server.
  8. The user is considered as authorized.
Query
projectIdstring(uuid)required
loginstringrequired

Login identifier of the user. Can be either an email address or phone number.

operation_idstringrequired

ID of the confirmation code. You can find its value in the response to a previous request.

curl --request GET \
  --url 'https://login.xsolla.com/api/otc/code?projectId=SOME_STRING_VALUE&login=SOME_STRING_VALUE&operation_id=SOME_STRING_VALUE'

Responses

OK

Bodyapplication/json
codestringrequired

Confirmation code.

Response
application/json
{
  "code": "string"
}

SSO

Operations

Client-side

Operations

Server-side

Operations

Validation schema

Operations