Custom storage

If you use custom storage, you have access to:

• user registration
• authentication via username and password
• passwordless authentication via phone number
• 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 requests to your server. Follow the instruction to validate the requests.
3. The Xsolla Login server processes a response from your server and returns the result to the client.
4. The client processes the response.

• As any JSON object.

• As an array of objects with user attributes. The objects should have the following structure:

User registration

1. The client sends the Register new user request to the Xsolla Login server.
2. The Xsolla Login server sends a request 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 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.

POST https://your.hostname/your_registration_uri HTTP/1.1
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "email":"j.smith@email.com",
  "password":"123456",
  "username":"j.smith@email.com"
}

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

Example of a response with user attributes:

{
    "attributes": [
      {
        "attr_type": "server",
        "key": "company",
        "permission": "private",
        "value": "facebook-promo"
      },
      {
        "attr_type": "server",
        "key": "custom-id",
        "permission": "private",
        "value": 48582
      }
    ]
}

Example of a response with a JSON object:

{ "region": "Asia",
  "type": "new"
}

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 011-002.
   • In the description parameter, provide the error message text.

{
  "error": {
    "code": "011-002",
    "description": "<string>"
  }
}

Authentication via username and password

1. The client sends the Auth by username and password request to the Xsolla Login server.
2. The Xsolla Login server sends a request 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 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.

POST https://your.hostname/your_authentication_uri HTTP/1.1
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "email":"j.smith@email.com",
  "password":"123456",
  "username":"j.smith@email.com"
}

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

Example of a response with user attributes:

{
    "attributes": [
      {
        "attr_type": "server",
        "key": "company",
        "permission": "private",
        "value": "facebook-promo"
      },
      {
        "attr_type": "server",
        "key": "custom-id",
        "permission": "private",
        "value": 48582
      }
    ]
}

Example of a response with a JSON object:

{ "region": "Asia",
  "type": "new"
}

3. The Xsolla Login server generates a user JWT.
4. 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 request to the Xsolla Login server.
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 request to the Xsolla Login server.
7. If it is the first user authorization, the Xsolla Login server sends a request to the Passwordless login with phone URL. The response must be in the format described in the interaction flow. In the response, you can specify a list of user attributes 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.

POST https://your.hostname/your_phone_authentication_uri HTTP/1.1
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "login": "+12025550140",
  "type": "phone"
}

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

Example of a response with user attributes:

{
    "attributes": [
      {
        "attr_type": "server",
        "key": "company",
        "permission": "private",
        "value": "facebook-promo"
      },
      {
        "attr_type": "server",
        "key": "custom-id",
        "permission": "private",
        "value": 48582
      }
    ]
}

Example of a response with a JSON object:

{ "region": "Asia",
  "type": "new"
}

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 request to the Xsolla Login server.
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 request to the Xsolla Login server.
7. If it is the first user authorization, the Xsolla Login server sends a request to the Passwordless login with email URL. The response must be in the format described in the interaction flow. In the response, you can specify a list of user attributes 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.

POST https://your.hostname/your_email_authentication_uri HTTP/1.1
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "email": "user@mail.com",
  "type": "email"
}

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

Example of a response with user attributes:

{
    "attributes": [
      {
        "attr_type": "server",
        "key": "company",
        "permission": "private",
        "value": "facebook-promo"
      },
      {
        "attr_type": "server",
        "key": "custom-id",
        "permission": "private",
        "value": 48582
      }
    ]
}

Example of a response with a JSON object:

{ "region": "Asia",
  "type": "new"
}

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 request to the Xsolla Login server.
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 request 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 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.

{
  "exp": 1573635020,
  "iat": 1573634600,
  "iss": "https://login.xsolla.com",
  "request_type": "gateway_request",
  "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000",
  "sub": "00000000-0000-0000-0000-000000000000",
  "email": "example@test.com",
  "username": "Smith707",
  "provider": "google",
  "id": "123",
}

New user URL response example:

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

{}

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

Example of a response with user attributes:

{
    "attributes": [
      {
        "attr_type": "server",
        "key": "company",
        "permission": "private",
        "value": "facebook-promo"
      },
      {
        "attr_type": "server",
        "key": "custom-id",
        "permission": "private",
        "value": 48582
      }
    ]
}

Example of a response with a JSON object:

{ "region": "Asia",
  "type": "new"
}

User password reset

1. The client sends the Reset password request to the Xsolla Login Server.
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 request to the Password reset URL.

New user URL response example:

POST https://your.hostname/your_reset_uri HTTP/1.1
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "username": "john@gmail.com",
  "fields": {
    "password": "NewPa$$word1"
  }
}

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

Continue reading