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

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

5. The Xsolla Login server processes a response from your server and returns the authorization token to the client.
6. The client sends the Generate JWT POST request to the Xsolla Login server. The request body must include the following required parameters:
   • grant_type — JWT grant type, pass the authorization_code value.
   • client_id — OAuth 2.0 client ID.
   • client_secret — OAuth 2.0 client secret ID. Required for confidential authentication type.
   • code — authorization code.
7. The Xsolla Login server returns a pair of JWTs to the client: an access token and a refresh token.
8. The client processes the response.
9. When the access token expires, the client sends the Generate JWT POST request to the Xsolla Login server. The request body must include the following required parameters:
   • grant_type — JWT grant type, pass the refresh_token value.
   • client_id — OAuth 2.0 client ID.
   • refresh_token — the refresh token received in the response to the user authorization request.

You can add user information to the JWT when identifying a user and/or refreshing a token, 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.

1. The client sends the Register new user POST request to the Xsolla Login server. The request must include 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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.

Example of an object with an error message:

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

1. The client sends the Register new userPOST request to the Xsolla Login server. The request must include the following required parameters:
   • Query parameters:
     • response_type — JWT grant type, pass the code value.
     • client_id — OAuth 2.0 client ID.
     • state — a value used for additional user authentication. Required to prevent CSRF attacks. Returned in the response. Allowed length: 1 to 8 characters.
   • 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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.

Example of an object with an error message:

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

1. The client sends the Auth by username and password POST request to the Xsolla Login server. The request must include 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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.

1. The client sends the Auth by username and passwordPOST request to the Xsolla Login server. The request must include the following required parameters:
   • Query parameters:
     • response_type — JWT grant type, pass the code value.
     • client_id — OAuth 2.0 client ID.
     • state — a value used for additional user authentication. Required to prevent CSRF attacks. Returned in the response. Allowed length: 1 to 8 characters.
   • 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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.

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

Webhook example:

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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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 numberPOST request to the Xsolla Login server. The request must include the following required parameters:
   • Query parameters:
     • response_type — JWT grant type, pass the code value.
     • client_id — OAuth 2.0 client ID.
     • state — a value used for additional user authentication. Required to prevent CSRF attacks. Returned in the response. Allowed length: 1 to 8 characters.
   • 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 numberPOST request to the Xsolla Login server. The request must include the following required parameters:
   • Query parameter client_id — OAuth 2.0 client ID.
   • 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.

Webhook example:

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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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 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 following required parameters:
   • The projectId query parameter — ID of the Login project in Publisher Account.
   • Body parameters:
     • 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

1. The client opens an authentication form so the user can enter their email.
2. The user enters their email.
3. The client sends the Start auth by emailPOST request to the Xsolla Login server. The request must include the following required parameters:
   • Query parameters:
     • response_type — JWT grant type, pass the code value.
     • client_id — OAuth 2.0 client ID.
     • state — a value used for additional user authentication. Required to prevent CSRF attacks. Returned in the response. Allowed length: 1 to 8 characters.
   • 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 emailPOST request to the Xsolla Login server. The request must include the following required parameters:
   • The client_id query parameter — OAuth 2.0 client ID.
   • Body parameters:
     • code — confirmation code.
     • email — user’s email.
     • 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

To get user data when authenticating via social networks, specify Social Login URL in the settings of your Login project in Publisher Account (the User database > Storage > Custom storage section). 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 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, xsolla, 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:

Example of a token payload:

 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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.

To get user data when authenticating via social networks, specify Social Login URL in the settings of your Login project in Publisher Account (the User database > Storage > Custom storage section). 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 following required parameters:
   • Query parameters:
     • response_type — JWT grant type, pass the code value.
     • client_id — OAuth 2.0 client ID.
     • state — a value used for additional user authentication. Required to prevent CSRF attacks. Returned in the response. Allowed length: 1 to 8 characters.
   • The provider_name path parameter — name of the social network connected to Login in Publisher Account. Can be: amazon, apple, xsolla, 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:

Example of a token payload:

 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  "user": {
 3    "player_id": "12345678",
 4    "email": "user@example.com"
 5  },
 6  "user_info": {
 7    "username": "gamer123",
 8    "user_first_name": "John",
 9    "user_last_name": "Doe",
10    "gender": "male",
11    "birthday": "1990-05-15",
12    "country": "US",
13    "language": "en"
14  },
15  "subscription_status": "active",
16  "loyalty_level": "gold"
17
18}

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.