Custom user data storage

If you use custom user data storage, Xsolla Login acts as an intermediary, and all user identification data is stored on your side. Xsolla Login passes authentication data in the a token included in the header of webhooks and in their bodies.

• user registration
• authentication via username and password
• passwordless authentication via phone number
• passwordless authentication via email
• authentication via social networks
• user password reset

Interaction flow

You can use the login widget or your application, that uses Login API calls, as a client. The interaction flow between the client and the Xsolla Login server is the following:

1. The client sends requests to the Xsolla Login server. The requests format is described in JWT and Password endpoints.
2. The Xsolla Login server sends webhooks to your server. The header includes a server JWT with the “request_type”: “gateway_token” parameter. To set up token validation, follow the instruction. A part of the user identification data is passed in the body of the webhook.
3. To confirm receipt of the webhook, your server must return:
   • 200, 201, or 204 HTTP code in case of a successful response.
   • 400 HTTP code with description of the problem if the specified user was not found or an invalid signature was passed. Your webhook handler may also return a 5xx HTTP code in case of temporary issues on your server.
4. The Xsolla Login server processes a response from your server and returns the authorization token to the client.
5. The client processes the response.

If you want to add user information to the JWT after user identification, return a JSON object with any set of parameters in the response body. This object will be saved in the partner_data field of the JWT.

• email address
• nickname
• date of birth
• first name
• last name
• user ID on your server

User registration

1. The client sends the Register new user POST request to the Xsolla Login server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • Body parameters:
     • username — user’s name. Allowed length: 3 to 255 characters.
     • password — user’s password. Allowed length: 6 to 100 characters.
     • email — user’s email address. Allowed length: 1 to 255 characters.
2. The Xsolla Login server sends a webhook to the New user URL. The response must be in the format described in the interaction flow. In the response, you can specify a list of user attributes and/or any necessary JSON object. The JSON object you provide in the response is recorded in the partner_data field of the user's JWT.

Webhook example:

1POST https://your.hostname/your_registration_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6  "email":"j.smith@email.com",
7  "password":"123456",
8  "username":"j.smith@email.com"
9}

1curl --request POST \
2  --url 'https://your.hostname/your_registration_uri' \
3  --header 'authorization: bearer_JWT' \
4  --header 'content-type: application/json' \
5  --data '{"email":"j.smith@email.com","password":"123456","username":"j.smith@email.com"}'

Example of a response to a webhook with user attributes:

 1{
 2    "attributes": [
 3      {
 4        "attr_type": "server",
 5        "key": "company",
 6        "permission": "private",
 7        "value": "facebook-promo"
 8      },
 9      {
10        "attr_type": "server",
11        "key": "custom-id",
12        "permission": "private",
13        "value": 48582
14      }
15    ]
16}

Example of a response to a webhook with a JSON object:

1{ 
2    "id": 123456,
3    "role": "scout"
4}

3. User data is written to the Xsolla database while the email is flagged as unconfirmed. The user will receive an account confirmation email.
4. If you have integrated the Login Widget, the user will be redirected to the page with the following message: Please confirm your account following the instructions we sent to {email}.
5. If user registration is unsuccessful, you can provide an error message that will be displayed in the authentication widget. To do this, in the response to the user creation request, pass the error object with the following details:
   • In the code parameter, specify an error code, for example 011-002.
   • In the description parameter, provide the error message text.

1{
2  "error": {
3    "code": "011-002",
4    "description": "<string>"
5  }
6}

Authentication via username and password

1. The client sends the Auth by username and password POST request to the Xsolla Login server.The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • Body parameters:
     • username — user’s name. Allowed length: 3 to 255 characters.
     • password — user’s password. Allowed length: 6 to 100 characters.
2. The Xsolla Login server sends a webhook to the User verification URL. The response must be in the format described in this interaction flow. In the response, you can specify a list of user attributes and/or any necessary JSON object. The JSON object you provide in the response is recorded in the partner_data field of the user's JWT.

User verification URL webhook example:

1POST https://your.hostname/your_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6  "email":"j.smith@email.com",
7  "password":"123456",
8  "username":"j.smith@email.com"
9}

1curl --request POST \
2  --url 'https://your.hostname/your_authentication_uri' \
3  --header 'authorization: bearer_JWT' \
4  --header 'content-type: application/json' \
5  --data '{"email":"j.smith@email.com","password":"123456","username":"j.smith@email.com"}'

Example of a response to a webhook with user attributes:

 1{
 2    "attributes": [
 3      {
 4        "attr_type": "server",
 5        "key": "company",
 6        "permission": "private",
 7        "value": "facebook-promo"
 8      },
 9      {
10        "attr_type": "server",
11        "key": "custom-id",
12        "permission": "private",
13        "value": 48582
14      }
15    ]
16}

Example of a response to a webhook with a JSON object:

1{ 
2    "id": 123456,
3    "role": "scout"
4}

3. If user authentication is unsuccessful, you can provide an error message that will be displayed in the authentication widget. To do this, in the response to the user creation request, pass the error object with the following details:
   • In the code parameter, specify an error code, for example 011-002.
   • In the description parameter, provide the error message text.
4. The Xsolla Login server generates a user JWT.
5. The user is redirected to the login_url with a token query parameter. The token parameter contains the user JWT.

Passwordless authentication via phone number

1. The client opens an authentication form so the user can enter their phone number.
2. The user enters their phone number.
3. The client sends the Start auth by phone number POST request to the Xsolla Login server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • The phone_number body parameter — user’s phone number.
4. The client shows a field so the user can fill in the verification code.
5. The user enters the received verification code.

6. The client sends the Complete auth by phone number POST request to the Xsolla Login server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • Body parameters:
     • code — confirmation code.
     • phone_number — user’s phone number.
     • operation_id — confirmation code ID.
7. If it is the first user authorization, the Xsolla Login server sends a webhook to the Passwordless login URL. The response must be in the format described in the interaction flow. In the response, you can specify a list of user attributes and/or any necessary JSON object. The JSON object you provide in the response is recorded in the partner_data field of the user's JWT.
8. If user authentication is unsuccessful, you can provide an error message that will be displayed in the authentication widget. To do this, in the response to the user creation request, pass the error object with the following details:
   • In the code parameter, specify an error code, for example 011-002.
   • In the description parameter, provide the error message text.

1POST https://your.hostname/your_phone_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6  "login": "+12025550140",
7  "type": "phone"
8}

1curl --request POST \
2  --url 'https://your.hostname/your_phone_authentication_uri' \
3  --header 'authorization: bearer_JWT' \
4  --header 'content-type: application/json' \
5  --data '{"login":"+12025550140","type":"phone"}'

Example of a response to a webhook with user attributes:

 1{
 2    "attributes": [
 3      {
 4        "attr_type": "server",
 5        "key": "company",
 6        "permission": "private",
 7        "value": "facebook-promo"
 8      },
 9      {
10        "attr_type": "server",
11        "key": "custom-id",
12        "permission": "private",
13        "value": 48582
14      }
15    ]
16}

Example of a response to a webhook with a JSON object:

1{ 
2    "id": 123456,
3    "role": "scout"
4}

Passwordless authentication via email

1. The client opens an authentication form so the user can enter their email address.
2. The user enters their email address.
3. The client sends the Start auth by email POST request to the Xsolla Login server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • The email body parameter — user’s email address.
4. The client shows a field so the user can fill in the verification code.
5. The user enters the received verification code.

6. The client sends the Complete auth by email POST request to the Xsolla Login server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • Body parameters:
     • username — user’s name. Allowed length: 3 to 255 characters.
     • code — confirmation code
     • email — user’s email address
     • operation_id — confirmation code ID
7. If it is the first user authorization, the Xsolla Login server sends a webhook to the Passwordless login URL. The response must be in the format described in the interaction flow. In the response, you can specify a list of user attributes and/or any necessary JSON object. The JSON object you provide in the response is recorded in the partner_data field of the user's JWT.
8. If user authentication is unsuccessful, you can provide an error message that will be displayed in the authentication widget. To do this, in the response to the user creation request, pass the error object with the following details:
   • In the code parameter, specify an error code, for example 011-002.
   • In the description parameter, provide the error message text.

Webhook example:

1POST https://your.hostname/your_email_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{
6  "email": "user@mail.com",
7  "type": "email"
8}

1curl --request POST \
2  --url 'https://your.hostname/your_email_authentication_uri' \
3  --header 'authorization: bearer_JWT' \
4  --header 'content-type: application/json' \
5  --data '{"email": "user@mail.com","type": "email"}'

Example of a response to a webhook with user attributes:

 1{
 2    "attributes": [
 3      {
 4        "attr_type": "server",
 5        "key": "company",
 6        "permission": "private",
 7        "value": "facebook-promo"
 8      },
 9      {
10        "attr_type": "server",
11        "key": "custom-id",
12        "permission": "private",
13        "value": 48582
14      }
15    ]
16}

Example of a response to a webhook with a JSON object:

1{ 
2    "id": 123456,
3    "role": "scout"
4}

Authentication via social networks

To get user data when authenticating via social networks, specify Social Login URL in the settings of your Login project in Publisher Account (section User database > Storage > Custom storage). A request with data received from the social network is sent to this URL.

Authentication flow:

1. The client sends the Auth via social network POST request to the Xsolla Login server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • The provider_name path parameter — name of the social network connected to Login in Publisher Account. Can be: amazon, apple, babka, baidu, battlenet, discord, epicgames, facebook, github, google, kakao, linkedin, mailru, microsoft, msn, naver, ok, paypal, qq, reddit, steam, twitch, twitter, vimeo, vk, wechat, weibo, xbox, yahoo, yandex, youtube.
2. The user logs into a social network.
3. The Xsolla Login server processes the user data received from the social network and sends a webhook to Social Login URL. The response must be in the format described in the interaction flow. In the response, you can specify a list of user attributes and/or any necessary JSON object. The JSON object you provide in the response is recorded in the partner_data field of the user’s JWT.

User data is passed in the Authorization header as a temporary gateway token (a server token with “request_type”: “gateway_token”). Main fields of the gateway token:

 1{
 2  "exp": 1573635020,
 3  "iat": 1573634600,
 4  "iss": "https://login.xsolla.com",
 5  "request_type": "gateway_request",
 6  "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000",
 7  "sub": "00000000-0000-0000-0000-000000000000",
 8  "email": "example@test.com",
 9  "username": "Smith707",
10  "provider": "google",
11  "id": "123",
12}

Social Login URL webhook example:

1POST https://your.hostname/your_social_authentication_uri HTTP/1.1
2Authorization: Bearer {JWT}
3Content-Type: application/json
4
5{}

1curl --request POST \
2  --url 'https://your.hostname/your_social_authentication_uri' \
3  --header 'authorization: bearer_JWT' \
4  --header 'content-type: application/json'

Example of a response to a webhook with user attributes:

 1{
 2    "attributes": [
 3      {
 4        "attr_type": "server",
 5        "key": "company",
 6        "permission": "private",
 7        "value": "facebook-promo"
 8      },
 9      {
10        "attr_type": "server",
11        "key": "custom-id",
12        "permission": "private",
13        "value": 48582
14      }
15    ]
16}

Example of a response to a webhook with a JSON object:

1{ 
2    "id": 123456,
3    "role": "scout"
4}

4. If user authentication is unsuccessful, you can provide an error message that will be displayed in the authentication widget. To do this, in the response to the user creation request, pass the error object with the following details:
   • In the code parameter, specify an error code, for example 011-002.
   • In the description parameter, provide the error message text.

User password reset

1. The client sends the Reset password POST request to the Xsolla Login Server. The request must include the Authorization: Bearer {JWT} header and the following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • The username body parameter — user’s name. Allowed length: 3 to 255 characters.
2. The Xsolla Login server sends the user a password reset confirmation email.
3. After confirming password reset in the email, the user is redirected to the page where they can enter a new password.
4. The user enters a new password.
5. The Xsolla Login server sends a webhook to the Password reset URL.
6. If a password reset is unsuccessful, you can provide an error message that will be displayed in the authentication widget. To do this, in the response to the user creation request, pass the error object with the following details:
   • In the code parameter, specify an error code, for example 011-002.
   • In the description parameter, provide the error message text.

Password reset URL webhook example:

 1POST https://your.hostname/your_reset_uri HTTP/1.1
 2Authorization: Bearer {JWT}
 3Content-Type: application/json
 4
 5{
 6  "username": "john@gmail.com",
 7  "fields": {
 8    "password": "NewPa$$word1"
 9  }
10}

1curl --request POST \
2  --url 'https://your.hostname/your_reset_uri' \
3  --header 'authorization: bearer_JWT' \
4  --header 'content-type: application/json' \
5  --data '{"email":"john@gmail.com","fields":{"password":"NewPa$$word1"}}'

Continue reading