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
1<script>
2const api = new XsollaLogin.Api({
3  projectId: 'someProjectId'
4});
5</script>

The initialization code when using an npm-package:

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

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 (cs_CZ), Filipino (fil_PH), English (en_XX), German (de_DE), Spanish (es_ES), French (fr_FR), Hebrew (he_IL), Indonesian (id_ID), Italian (it_IT), Japanese (ja_JP), Khmer (km-KH), Korean (ko_KR), Lao ( lo_LA), Myanmar (my_MM), Nepali (ne_NP), 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
 1let result
 2// Request
 3api.signup({
 4  userInfo: {
 5    email: 'email@address.com',
 6    fields: {
 7      nickname: 'Johny'
 8    },
 9    password: 'password123',
10    username: 'John'
11  }
12}).then((res) => {
13  result = res;
14})
15
16// Response
17result === {
18  login_url: 'https://someurl.com?token=XXXXXXX'
19}

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
 1let result
 2// Request
 3api.login({
 4  credentials: {
 5    password: 'password123',
 6    username: 'email@address.com'
 7  }
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17// Response with additional fields
18result === {
19  ask_fields: [{
20    confirmation_type: 'code' || 'link'
21    name: 'phone_number'
22    required: false
23    step: 0 // Displays the position of the field in the data retrieval queue.
24    type: 'phone'
25    validation: {} // Custom validation
26  }]
27  login_url: 'https://someurl.com?token=XXXXXXX',
28  token: 'sometoken'
29}

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
1// Request
2api.resendEmail({
3  username: "email@address.com"
4}).then((res) => {
5  if (res.code === 204) {
6    console.log("Email resend success");
7  }
8});

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
 1let result
 2// Request
 3api.phoneGetCode({
 4  phone_number: '+somenumber',
 5  link_url: 'https://someurl.com',
 6  isOauth2: true
 7}).then((res) => {
 8  result = res;
 9})
10
11// Response
12result === {
13  operation_id: '2334j255fdf13d515fgd1'
14}
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
 1let result
 2// Request
 3api.emailGetCode({
 4  email: 'email@address.com',
 5  link_url: 'https://someurl.com',
 6  isOauth2: true
 7}).then((res) => {
 8  result = res;
 9})
10
11// Response
12result === {
13  operation_id: '2334j255fdf13d515fgd1'
14}
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
 1let result
 2// Request
 3const axiosCancelToken = Axios.CancelToken.source();
 4
 5api.getConfirmCode({
 6  cancelToken: axiosCancelToken,
 7  login: '+somenumber' || 'email@address.com',
 8  operation_id: '334j255fdf13d515fgd1'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  code: 'string'
16}
17
18// If the waiting time has elapsed, returns:
19result === {
20  error: {
21    code: '010-050',
22    description: 'Deadline exceeded.'
23  }
24}
25
26// If you no longer need to wait for verification through the link you can close the request waiting period:
27axiosCancelToken.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
 1let result
 2// Request
 3api.loginWithPhoneCode({
 4  phone_number: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17
18// Response with additional fields
19result === {
20  ask_fields: [{
21    confirmation_type: 'code' || 'link'
22    name: 'email'
23    required: false
24    step: 0 // Displays the position of the field in the data retrieval queue.
25    type: 'email'
26    validation: {} // Custom validation
27  }]
28  login_url: 'https://someurl.com?token=XXXXXXX',
29  token: 'sometoken'
30}
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
 1let result
 2// Request
 3api.loginWithEmailCode({
 4  email: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17// Response with additional fields
18result === {
19  ask_fields: [{
20    confirmation_type: 'code' || 'link'
21    name: 'phone_number'
22    required: false
23    step: 0 // Displays the position of the field in the data retrieval queue.
24    type: 'phone'
25    validation: {} // Custom validation
26  }]
27  login_url: 'https://someurl.com?token=XXXXXXX',
28  token: 'sometoken'
29}

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
 1let result
 2// Request
 3api.getAskFields({
 4  token: 'sometoken'
 5}).then((res) => {
 6  result = res;
 7})
 8
 9// Response
10result === [
11  {
12    confirmation_type: 'code' || 'link'
13    name: 'phone_number' || 'email'
14    required: false
15    step: 0 // Displays the position of the field in the data retrieval queue.
16    type: 'phone' || 'email'
17    validation: {} // Custom validation
18  }
19]
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
 1let result
 2// Request
 3api.ask({
 4  fields: {  
 5    phone_number: '+somenumber'
 6  },
 7  link_url: 'https://someurl.com',
 8  token: 'sometoken'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  error: {
16    code: '003-014'
17    description: 'Confirm phone number.'
18    details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
19  }
20}
21
22// Response without confirmation
23result === {
24  redirect_url: '<login_url>?token=<token>'
25}

Example of sending an email address:

Copy
Full screen
Small screen
 1let result
 2// request
 3api.ask({
 4  fields: {  
 5    email: 'email@address.com'
 6  },
 7  link_url: 'https://someurl.com',
 8  token: 'sometoken'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  error: {
16    code: '003-011'
17    description: 'Confirm email.'
18    details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
19  }
20}
21
22// Response without confirmation
23result === {
24  redirect_url: '<login_url>?token=<token>'
25}
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
 1let result
 2// Request
 3const axiosCancelToken = Axios.CancelToken.source();
 4
 5api.getConfirmCode({
 6  cancelToken: axiosCancelToken,
 7  login: '+somenumber' || 'email@address.com',
 8  operation_id: '334j255fdf13d515fgd1'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  code: 'string'
16}
17
18// If the waiting time has elapsed, returns:
19result === {
20  error: {
21    code: '010-050',
22    description: 'Deadline exceeded.'
23  }
24}
25
26// If you no longer need to wait for verification through the link you can close the request waiting period:
27axiosCancelToken.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
 1let result
 2// Request
 3api.loginWithPhoneCode({
 4  phone_number: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17
18// Response with additional fields
19result === {
20  ask_fields: [{
21    confirmation_type: 'code' || 'link'
22    name: 'email'
23    required: false
24    step: 0 // Displays the position of the field in the data retrieval queue.
25    type: 'email'
26    validation: {} // Custom validation
27  }]
28  login_url: 'https://someurl.com?token=XXXXXXX',
29  token: 'sometoken'
30}
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
 1let result
 2// Request
 3api.loginWithEmailCode({
 4  email: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17// Response with additional fields
18result === {
19  ask_fields: [{
20    confirmation_type: 'code' || 'link'
21    name: 'phone_number'
22    required: false
23    step: 0 // Displays the position of the field in the data retrieval queue.
24    type: 'phone'
25    validation: {} // Custom validation
26  }]
27  login_url: 'https://someurl.com?token=XXXXXXX',
28  token: 'sometoken'
29}

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
1let result
2// Request
3api.reset({
4  username: 'John'
5}).then((res) => {
6  res.code === 204;
7})
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
1let result
2// Request
3api.set({
4  new_password: 'newpass',
5  reset_code: '3423',
6  user_id: '324324234'
7}).then((res) => {
8  res.code === 204;
9})

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
 1let result
 2// Request
 3api
 4  .checkUserAuthSSO()
 5  .then(res => {
 6    result === res;
 7  });
 8
 9result === {
10  code: "examplecode"
11}
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
1// Request
2api
3  .userAuthSSOWithRedirect(
4    loginUrl: 'some-redirect-url.com'
5  )
6  .then(res => {
7    res.code === 302;
8  });
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
1// Request
2api
3  .logout(
4    token: 'exampleToken',
5    session: 'sso' | 'all'
6  )
7  .then(res => {
8    res.code === 204;
9  });
ParameterTypeDescription
api.clearSSO();
Removes the Single Sign-on cookie files from the current user’s device. The 204 code is returned in the response if the call is successful.
Example:
Copy
Full screen
Small screen
1// Request
2api
3  .clearSSO()
4  .then(() => {
5    // Success
6  });
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.
Last updated: September 19, 2025

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!
We couldn't send your feedback
Try again later or contact us at doc_feedback@xsolla.com.