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

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:

Parameter	Type	Description
projectId	string	ID of your Login project from Publisher Account. Required.
fullLocale	string	The interface language and a region in the `<language code>_<country code>` format, where: `language code` — language code per ISO 639-1. `country code` — country code per ISO 3166-1 alpha-2. The following languages are supported: Arabic (ar_AE), Bulgarian (bg_BG), Czech (cz_CZ), English (en_XX), 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	string	The URL the Xsolla Login server works with if login or sign-up is successful.
emailTemplate	string	The name of the project on behalf of which the emails are sent to users.
payload	string	Additional data that can be passed in a code. This data is added to the user JWT after successful login.
with_logout	boolean	Whether to revoke previous tokens during a new login. `false` by default.
clientId	string	ID of the client app. Passed if the OAuth 2.0 protocol-based authentication is used in the app.
scope	string	Additional 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	string	An additional user verification to prevent CSRF attacks for example. Must be longer than 8 characters.
redirectUrl	string	The URL the user is redirected to after they confirm their account, log in, or confirm password reset.
disableConfirmByLink	boolean	Whether 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	boolean	Whether 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

Call	Description	Parameters
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

Call	Description	Parameters
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

Call	Description	Parameters
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:

The user enters their phone number or email address. Depending on the credentials they entered, either api.phoneGetCode or api.emailGetCode is called.
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.
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.
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.

Call	Description	Parameters
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'
}

Call	Description	Parameters
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'
}

Call	Description	Parameters
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();

Call	Description	Parameters
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'
}

Call	Description	Parameters
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:

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.
The user enters a phone number or email address. The api.ask is executed.
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.
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.
The URL that is used for a redirect to an authenticated user is returned after successful data confirmation.

Call	Description	Parameters
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
  }
]

Call	Description	Parameters
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>'
}

Call	Description	Parameters
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();

Call	Description	Parameters
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'
}

Call	Description	Parameters
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:

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

Call	Description	Parameters
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;
})

Call	Description	Parameters
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

See the instruction about Single Sign-On for detailed information.

Parameter	Type	Description
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"
}

Call	Description	Parameters
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;
  });

Call	Description	Parameters
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;
  });

Parameter	Type	Description
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

// Request
api
  .clearSSO()
  .then(() => {
    // Success
  });

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: January 22, 2024

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

Your browser is not supported. Please try a different browser

Popular articles

Or choose frequently asked ones:

Answer based on the following sources:

Leave us some feedback (optional)

Leave us some feedback (optional)

Login

How to use Login Widget SDK API calls

Code initialization

projectId

fullLocale

callbackUrl

emailTemplate

payload

with_logout

clientId

scope

state

redirectUrl

disableConfirmByLink

is_oauth2

API calls

User registration by password

Login with password

Account confirmation

Passwordless authentication

Additional fields requests without password

Password reset

Single Sign-On

api.checkUserAuthSSO();

api.clearSSO();