How to use Login Widget SDK API calls

You can work with the Login Widget SDK API calls separately from the Login widget if you want to:

  • use your own widget design
  • partly implement the Login widget flow

Note
Not all API calls support this scenario.

Code initialization

To use the Login Widget SDK API calls without a widget, connect the following code to the <body> tag:

Copy
Full screen
Small screen
    <script>
    const api = new XsollaLogin.Api({
      projectId: 'someProjectId'
    });
    </script>

    The initialization code when using an npm-package:

    Copy
    Full screen
    Small screen
      import XsollaLogin from '@xsolla/login-sdk';
      const api = new XsollaLogin.Api({
        projectId: 'someProjectId'
      });

      The following parameters are passed in the initialization code:

      ParameterTypeDescription
      projectId
      stringID of your Login project from Publisher Account. Required.
      fullLocale
      stringThe interface language and a region in the <language code>_<country code> format, where:The following languages are supported: Arabic (ar_AE), Bulgarian (bg_BG), Czech (cz_CZ), German (de_DE), Spanish (es_ES), French (fr_FR), Hebrew (he_IL), Italian (it_IT), Japanese (ja_JP), Korean (ko_KR), Polish (pl_PL), Portuguese (pt_BR), Romanian (ro_RO), Russian (ru_RU), Thai (th_TH), Turkish (tr_TR), Vietnamese (vi_VN), Chinese Simplified (zh_CN), Chinese Traditional (zh_TW).
      The parameter affects sorting of social networks by the frequency of use in the specified region and also affects the language used for emails sent to users.
      callbackUrl
      stringThe URL the Xsolla Login server works with if login or sign-up is successful.
      emailTemplate
      stringThe name of the project on behalf of which the emails are sent to users.
      payload
      stringAdditional data that can be passed in a code. This data is added to the user JWT after successful login.
      with_logout
      booleanWhether to revoke previous tokens during a new login. false by default.
      clientId
      stringID of the client app. Passed if the OAuth 2.0 protocol-based authentication is used in the app.
      scope
      stringAdditional info about a user account requested by the app. Passed if the OAuth 2.0 protocol-based authentication is used in the app. Possible values:
      • email — an additional request of the user email address during social login.
      • offline — an automatic update of the JWT after it expires.
      • playfab — the SessionTicket parameter is automatically passed to a JWT if the user data is stored in PlayFab.
      You can also specify your own parameters. The Xsolla Login Server does not process them but returns them to a JWT.
      state
      stringAn additional user verification to prevent CSRF attacks for example. Must be longer than 8 characters.
      redirectUrl
      stringThe URL the user is redirected to after they confirm their account, log in, or confirm password reset.
      booleanWhether to disable the confirmation of passwordless authentication by a link in the email when users log in without a password by email or phone. false by default.
      is_oauth2
      booleanWhether to use the OAuth 2.0 protocol-based authentication for users. false by default.

      API calls

      You can use the following Login Widget SDK API calls without a Login widget:

      User registration by password

      CallDescriptionParameters
      api.signup(userInfo);Registers a new user. The data about the user is passed in the userInfo object during registration. The token of the registered user is passed in the response.
      • email (string) — User email address. Required.
      • username (string) — Username. Required.
      • password (string) — User password. Required.
      • nickname (string) — User nickname.

      Example:

      Copy
      Full screen
      Small screen
        let result
        // Request
        api.signup({
          userInfo: {
            email: 'email@address.com',
            fields: {
              nickname: 'Johny'
            },
            password: 'password123',
            username: 'John'
          }
        }).then((res) => {
          result = res;
        })
        
        // Response
        result === {
          login_url: 'https://someurl.com?token=XXXXXXX'
        }

        Login with password

        CallDescriptionParameters
        api.login(credentials);Authenticates a user with a password. The data about the user required for user login is passed in the credentials object. The token of the authenticated user is passed in the response.
        • username (string) — User name, for example — John, or an email address, for example — email@address.com. Required.
        • password (string) — User password. Required.

        Example:

        Copy
        Full screen
        Small screen
          let result
          // Request
          api.login({
            credentials: {
              password: 'password123',
              username: 'email@address.com'
            }
          }).then((res) => {
            result = res;
          })
          
          // Response
          result === {
            login_url: 'https://someurl.com?token=XXXXXXX'
          }
          
          // Response with additional fields
          result === {
            ask_fields: [{
              confirmation_type: 'code' || 'link'
              name: 'phone_number'
              required: false
              step: 0 // Displays the position of the field in the data retrieval queue.
              type: 'phone'
              validation: {} // Custom validation
            }]
            login_url: 'https://someurl.com?token=XXXXXXX',
            token: 'sometoken'
          }

          Account confirmation

          CallDescriptionParameters
          api.resendEmail(username);Sends an additional account confirmation email. To confirm the account, the user should click the link in the email. The user email address is passed in the username object. The standard code 204 is returned in the response.
          • username (string) — User email address, for example — email@address.com. Required.

          Example:

          Copy
          Full screen
          Small screen
            let result
            // Request
            api.resendEmail({
              username: 'email@address.com'
            }).then((res) => {
              res.code === 204;
            })

            Passwordless authentication

            User flow:

            1. The user enters their phone number or email address. Depending on the credentials they entered, either api.phoneGetCode or api.emailGetCode is called.
            2. The server receives the data and sends an email or SMS with the code to the user. If the disableConfirmByLink=true parameter, that disables login confirmation by the link in the email, is passed when initializing the code, the api.getConfirmCode call is used for the automatic user redirection after clicking the link.
            3. The api.phoneGetCode or api.emailGetCode call returns the operation_id parameter used to confirm the phone number or email address by the api.loginWithPhoneCode or api.loginWithEmailCode call.
            4. After the email address or phone number is successfully confirmed, the URL with the token parameter returns. It’s used in the requests for additional data about the user.

            CallDescriptionParameters
            api.phoneGetCode({ phone_number, link_url, isOauth2 });Sends a confirmation code to the phone number. The operation_id parameter used to confirm the phone number is returned in the response.
            • phone_number (string) — Phone number for passwordless authentication.
            • link_url (string) — Confirmation URL.
            • isOauth2 (boolean) — Whether to use the OAuth 2.0 protocol-based authentication for users. Required.

            Example:

            Copy
            Full screen
            Small screen
              let result
              // Request
              api.phoneGetCode({
                phone_number: '+somenumber',
                link_url: 'https://someurl.com',
                isOauth2: true
              }).then((res) => {
                result = res;
              })
              
              // Response
              result === {
                operation_id: '2334j255fdf13d515fgd1'
              }

              CallDescriptionParameters
              api.phoneGetCode({ phone_number, link_url, isOauth2 });Sends a confirmation code to the email address. The operation_id parameter used to confirm the email address is returned in the response.
              • email (string) — Email address for passwordless authentication.
              • link_url (string) — Confirmation URL.
              • isOauth2 (boolean) — Whether to use the OAuth 2.0 protocol-based authentication for users. Required.

              Example:

              Copy
              Full screen
              Small screen
                let result
                // Request
                api.emailGetCode({
                  email: 'email@address.com',
                  link_url: 'https://someurl.com',
                  isOauth2: true
                }).then((res) => {
                  result = res;
                })
                
                // Response
                result === {
                  operation_id: '2334j255fdf13d515fgd1'
                }

                CallDescriptionParameters
                api.getConfirmCode({ cancelToken, login, operation_id });Gets a confirmation code for an automatic redirection of a user after they click the link.
                • cancelToken (string) — Unique token to end the session. Required.
                • login (string) — User phone number or email address. Required.
                • operation_id (string) — Unique identifier used to confirm a user phone number or email address during a current session. Required.

                Example:

                Copy
                Full screen
                Small screen
                  let result
                  // Request
                  const axiosCancelToken = Axios.CancelToken.source();
                  
                  api.getConfirmCode({
                    cancelToken: axiosCancelToken,
                    login: '+somenumber' || 'email@address.com',
                    operation_id: '334j255fdf13d515fgd1'
                  }).then((res) => {
                    result = res;
                  })
                  
                  // Response
                  result === {
                    code: 'string'
                  }
                  
                  // If the waiting time has elapsed, returns:
                  result === {
                    error: {
                      code: '010-050',
                      description: 'Deadline exceeded.'
                    }
                  }
                  
                  // If you no longer need to wait for verification through the link you can close the request waiting period:
                  axiosCancelToken.cancel();

                  CallDescriptionParameters
                  api.loginWithPhoneCode({ phone_number, code, operation_id, isOauth2 });Confirms phone number. The URL with the token parameter returns in the response. It’s used in the requests for additional data about the user.
                  • phone_number (string) — Phone number for passwordless authentication.
                  • code (string) — Phone confirmation code sent as an SMS.
                  • operation_id (string) — Unique identifier used to confirm a user phone number during a current session.
                  • isOauth2 (boolean) — Whether to use the OAuth 2.0 protocol-based authentication for users. Required.

                  Example:

                  Copy
                  Full screen
                  Small screen
                    let result
                    // Request
                    api.loginWithPhoneCode({
                      phone_number: 'email@address.com',
                      code: '3423',
                      operation_id: '334j255fdf13d515fgd1',
                      isOauth2: true
                    }).then((res) => {
                      result = res;
                    })
                    
                    // Response
                    result === {
                      login_url: 'https://someurl.com?token=XXXXXXX'
                    }
                    
                    
                    // Response with additional fields
                    result === {
                      ask_fields: [{
                        confirmation_type: 'code' || 'link'
                        name: 'email'
                        required: false
                        step: 0 // Displays the position of the field in the data retrieval queue.
                        type: 'email'
                        validation: {} // Custom validation
                      }]
                      login_url: 'https://someurl.com?token=XXXXXXX',
                      token: 'sometoken'
                    }

                    CallDescriptionParameters
                    api.loginWithEmailCode({ email, code, operation_id, isOauth2 });Confirms email address. The URL with the token parameter returns in the response. It’s used in the requests for additional data about the user.
                    • email (string) — Email address for passwordless authentication.
                    • code (string) — Confirmation code sent in an email.
                    • operation_id (string) — Unique identifier used to confirm an email address during a current session.
                    • isOauth2 (boolean) — Whether to use the OAuth 2.0 protocol-based authentication for users. Required.

                    Example:

                    Copy
                    Full screen
                    Small screen
                      let result
                      // Request
                      api.loginWithEmailCode({
                        email: 'email@address.com',
                        code: '3423',
                        operation_id: '334j255fdf13d515fgd1',
                        isOauth2: true
                      }).then((res) => {
                        result = res;
                      })
                      
                      // Response
                      result === {
                        login_url: 'https://someurl.com?token=XXXXXXX'
                      }
                      
                      // Response with additional fields
                      result === {
                        ask_fields: [{
                          confirmation_type: 'code' || 'link'
                          name: 'phone_number'
                          required: false
                          step: 0 // Displays the position of the field in the data retrieval queue.
                          type: 'phone'
                          validation: {} // Custom validation
                        }]
                        login_url: 'https://someurl.com?token=XXXXXXX',
                        token: 'sometoken'
                      }

                      Additional fields requests without password

                      User flow:

                      1. After successful authentication of a user, the api.loginWithEmailCode or api.loginWithPhoneCode call returns an array of fields that you can display in an app in a separate form and additionally collect the user phone number and email address. You can also get the list of fields by executing an api.getAskFields call.
                      2. The user enters a phone number or email address. The api.ask is executed.
                      3. The server receives the data and sends a confirmation code to a phone number or email address. If the disableConfirmByLink=true parameter, that disables login confirmation by the link in the email, is passed when initializing the code, the api.getConfirmCode call is used for the automatic user redirection after clicking the link.
                      4. The api.ask call returns the operation_id parameter used to confirm the phone number or email address by the api.loginWithPhoneCode or api.loginWithEmailCode call.
                      5. The URL that is used for a redirect to an authenticated user is returned after successful data confirmation.

                      CallDescriptionParameters
                      api.getAskFields(token);Gets the list of fields for an additional request.
                      • token (string) — User JWT. Required.

                      Example:

                      Copy
                      Full screen
                      Small screen
                        let result
                        // Request
                        api.getAskFields({
                          token: 'sometoken'
                        }).then((res) => {
                          result = res;
                        })
                        
                        // Response
                        result === [
                          {
                            confirmation_type: 'code' || 'link'
                            name: 'phone_number' || 'email'
                            required: false
                            step: 0 // Displays the position of the field in the data retrieval queue.
                            type: 'phone' || 'email'
                            validation: {} // Custom validation
                          }
                        ]

                        CallDescriptionParameters
                        api.ask({ fields, token, link_url });Sends additional data about the user — a phone number or email address. The operation_id parameter that is used to confirm the specified phone number or email address is returned in the response. If the confirmation is not required, the URL with the token parameter that is used for a redirect to an authenticated user is returned in the response.
                        • fields (object) — Object where the user phone or email address is passed. Required.
                        • token (string) — User JWT. Required.
                        • link_url (string) — Confirmation URL.

                        An example of sending a phone number:

                        Copy
                        Full screen
                        Small screen
                          let result
                          // Request
                          api.ask({
                            fields: {  
                              phone_number: '+somenumber'
                            },
                            link_url: 'https://someurl.com',
                            token: 'sometoken'
                          }).then((res) => {
                            result = res;
                          })
                          
                          // Response
                          result === {
                            error: {
                              code: '003-014'
                              description: 'Confirm phone number.'
                              details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
                            }
                          }
                          
                          // Response without confirmation
                          result === {
                            redirect_url: '<login_url>?token=<token>'
                          }

                          Example of sending an email address:

                          Copy
                          Full screen
                          Small screen
                            let result
                            // request
                            api.ask({
                              fields: {  
                                email: 'email@address.com'
                              },
                              link_url: 'https://someurl.com',
                              token: 'sometoken'
                            }).then((res) => {
                              result = res;
                            })
                            
                            // Response
                            result === {
                              error: {
                                code: '003-011'
                                description: 'Confirm email.'
                                details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
                              }
                            }
                            
                            // Response without confirmation
                            result === {
                              redirect_url: '<login_url>?token=<token>'
                            }

                            CallDescriptionParameters
                            api.getConfirmCode({ cancelToken, login, operation_id });Gets confirmation code for an automatic redirect of a user after clicking the link.
                            • cancelToken (string) — Unique token to end the session. Required.
                            • login (string) — User phone number or email address. Required.
                            • operation_id (string) — Unique identifier used to confirm a user phone number or email address during a current session. Required.

                            Example:

                            Copy
                            Full screen
                            Small screen
                              let result
                              // Request
                              const axiosCancelToken = Axios.CancelToken.source();
                              
                              api.getConfirmCode({
                                cancelToken: axiosCancelToken,
                                login: '+somenumber' || 'email@address.com',
                                operation_id: '334j255fdf13d515fgd1'
                              }).then((res) => {
                                result = res;
                              })
                              
                              // Response
                              result === {
                                code: 'string'
                              }
                              
                              // If the waiting time has elapsed, returns:
                              result === {
                                error: {
                                  code: '010-050',
                                  description: 'Deadline exceeded.'
                                }
                              }
                              
                              // If you no longer need to wait for verification through the link you can close the request waiting period:
                              axiosCancelToken.cancel();

                              CallDescriptionParameters
                              api.loginWithPhoneCode({ phone_number, code, operation_id, isOauth2 });Confirms phone number. The URL with the token parameter returns in the response. It’s used in the requests for additional data about the user.
                              • phone_number (string) — Phone number for passwordless authentication.
                              • code (string) — Phone confirmation code sent as an SMS.
                              • operation_id (string) — Unique identifier used to confirm a user phone number during a current session.
                              • isOauth2 (boolean) — Whether to use the OAuth 2.0 protocol-based authentication for users. Required.

                              Example:

                              Copy
                              Full screen
                              Small screen
                                let result
                                // Request
                                api.loginWithPhoneCode({
                                  phone_number: 'email@address.com',
                                  code: '3423',
                                  operation_id: '334j255fdf13d515fgd1',
                                  isOauth2: true
                                }).then((res) => {
                                  result = res;
                                })
                                
                                // Response
                                result === {
                                  login_url: 'https://someurl.com?token=XXXXXXX'
                                }
                                
                                
                                // Response with additional fields
                                result === {
                                  ask_fields: [{
                                    confirmation_type: 'code' || 'link'
                                    name: 'email'
                                    required: false
                                    step: 0 // Displays the position of the field in the data retrieval queue.
                                    type: 'email'
                                    validation: {} // Custom validation
                                  }]
                                  login_url: 'https://someurl.com?token=XXXXXXX',
                                  token: 'sometoken'
                                }

                                CallDescriptionParameters
                                api.loginWithEmailCode({ email, code, operation_id, isOauth2 });Confirms email address. The URL with the token parameter returns in the response. It’s used in the requests for additional data about the user.
                                • email (string) — Email address for passwordless authentication.
                                • code (string) — Confirmation code sent to the email address.
                                • operation_id (string) — Unique identifier used to confirm a user email address during a current session.
                                • isOauth2 (boolean) — Whether to use the OAuth 2.0 protocol-based authentication for users. Required.

                                Example:

                                Copy
                                Full screen
                                Small screen
                                  let result
                                  // Request
                                  api.loginWithEmailCode({
                                    email: 'email@address.com',
                                    code: '3423',
                                    operation_id: '334j255fdf13d515fgd1',
                                    isOauth2: true
                                  }).then((res) => {
                                    result = res;
                                  })
                                  
                                  // Response
                                  result === {
                                    login_url: 'https://someurl.com?token=XXXXXXX'
                                  }
                                  
                                  // Response with additional fields
                                  result === {
                                    ask_fields: [{
                                      confirmation_type: 'code' || 'link'
                                      name: 'phone_number'
                                      required: false
                                      step: 0 // Displays the position of the field in the data retrieval queue.
                                      type: 'phone'
                                      validation: {} // Custom validation
                                    }]
                                    login_url: 'https://someurl.com?token=XXXXXXX',
                                    token: 'sometoken'
                                  }

                                  Password reset

                                  User flow:

                                  1. The application opens the form where the user enters their email address or username. The api.reset call is executed.
                                  2. The server sends a confirmation email to the user.
                                  3. The user clicks the link in the email and opens a form for a new password.
                                  4. The user enters a new password. The api.set call is executed.

                                  CallDescriptionParameters
                                  api.reset(username);Resets password and confirms the action. To confirm a password reset, the user should click the link in the email. The username or user email address is passed in the username object. The 204 code is returned in the response.
                                  • username (string) — User name, for example — John, or an email address, for example — email@address.com. Required.

                                  Example:

                                  Copy
                                  Full screen
                                  Small screen
                                    let result
                                    // Request
                                    api.reset({
                                      username: 'John'
                                    }).then((res) => {
                                      res.code === 204;
                                    })

                                    CallDescriptionParameters
                                    api.set({ new_password, reset_code, user_id });Sets new password and confirms the action. To confirm a new password, the user should click the link in the email. The 204 code is returned in the response.
                                    • new_password (string) — A new password entered by a user. Required.
                                    • reset_code (string) — A code used for verification of a user who sent a request for a password change. The code is generated on the server side and is passed in the URL the user is redirected to after clicking the link in the email. Required.
                                    • user_id (string) — User identifier. It’s generated on the server side and is passed in the URL the user is redirected to after clicking the link in the email. Required.

                                    Example:

                                    Copy
                                    Full screen
                                    Small screen
                                      let result
                                      // Request
                                      api.set({
                                        new_password: 'newpass',
                                        reset_code: '3423',
                                        user_id: '324324234'
                                      }).then((res) => {
                                        res.code === 204;
                                      })

                                      Single Sign-On

                                      Note
                                      ParameterTypeDescription
                                      api.checkUserAuthSSO();
                                      Checks whether a user is authorized via Single Sign-On. If successful, a one-time code returns.

                                      Example:

                                      Copy
                                      Full screen
                                      Small screen
                                        let result
                                        // Request
                                        api
                                          .checkUserAuthSSO()
                                          .then(res => {
                                            result === res;
                                          });
                                        
                                        result === {
                                          code: "examplecode"
                                        }

                                        CallDescriptionParameters
                                        api.userAuthSSOWithRedirect(loginUrl);Checks whether a user authorized via Single Sign-On. If successful, a user is redirected to the URL — generated loginUrl including an authorization code.
                                        • loginUrl (string) — URL where a user is redirected to after a SSO check. It has to be the same as the Callback URL indicated in the URL block in Publisher Account in your Login project > General settings. Required when there are several URL addresses where a user can be redirected to.

                                        Example:

                                        Copy
                                        Full screen
                                        Small screen
                                          // Request
                                          api
                                            .userAuthSSOWithRedirect(
                                              loginUrl: 'some-redirect-url.com'
                                            )
                                            .then(res => {
                                              res.code === 302;
                                            });

                                          CallDescriptionParameters
                                          api.logout(token, session);Logs out a user of the system and deletes a user session according to the session parameter.
                                          • token (string) — the user JWT. Required.
                                          • session (string) — shows how a user logs out of the system and how their session is deleted. Required. Can be:
                                            • sso — deletes only the SSO user session.
                                            • all — deletes the SSO user session and all access tokens and updates.

                                          Example:

                                          Copy
                                          Full screen
                                          Small screen
                                            // Request
                                            api
                                              .logout(
                                                token: 'exampleToken',
                                                session: 'sso' | 'all'
                                              )
                                              .then(res => {
                                                res.code === 204;
                                              });

                                            Was this article helpful?
                                            Thank you!
                                            Is there anything we can improve? Message
                                            We’re sorry to hear that
                                            Please explain why this article wasn’t helpful to you. Message
                                            Thank you for your feedback!
                                            We’ll review your message and use it to help us improve your experience.
                                            Rate this page
                                            Rate this page
                                            Is there anything we can improve?

                                            Don’t want to answer

                                            Thank you for your feedback!
                                            Last updated: October 21, 2021

                                            Found a typo or other text error? Select the text and press Ctrl+Enter.

                                            Report a problem
                                            We always review our content. Your feedback helps us improve it.
                                            Provide an email so we can follow up
                                            Thank you for your feedback!