Login / Logout
Once a user has signed up, they can log in to your project using their email and password.
Login
Use the login() method to log a user into your project.
The e-mail address is matched without regard to letter case: Ana@Example.com and ana@example.com reach the same account, and an address typed with Caps Lock on still signs in. A username chosen at sign-up keeps its case.
If the login is not successful due to invalid password, or user may not have confirm their signup etc... the login() method will throw an error.
When successful, it will respond with the UserProfile object.
WARNING
If signup_confirmation option was set to true during signup(), users will not be able to log in until they have confirmed their account.
INFO
When the user has successfully confirmed their signup and logged in, they will be sent a welcome email. You can also customize the email template for the signup confirmation email.
For more info on email templates, see Automated E-Mail.
Below is an example of a login form that uses the login() method. When the user successfully logs in, they will be redirected to the welcome.html page.
<form
action="welcome.html"
onsubmit="skapi.login(event).catch(err=>alert(err.message))"
>
<h2>Login</h2>
<hr />
<label>
E-Mail<br />
<input
type="email"
name="email"
placeholder="user@email.com"
required
/> </label
><br /><br />
<label>
Password<br />
<input
id="password"
type="password"
name="password"
placeholder="Your password"
required
/> </label
><br /><br />
<input type="submit" value="Login" />
</form>let parameters = {
email: "user@email.com",
password: "password",
};
skapi.login(parameters).then((user) => (window.location.href = "welcome.html"));For more detailed information on all the parameters and options available with the login() method, please refer to the API Reference below:
login(params): Promise<UserProfile>
If the account was created with a username, the username logs the user in from the moment the account is created, and the account's current email does too once that address is verified. Pass whichever the user typed. Until the address is verified, by the signup confirmation link, by accepting an invitation or by verifyEmail(), only the username reaches the account, and the email answers INCORRECT_USERNAME_OR_PASSWORD. Email login then starts a few seconds after the verification, on the account's next token.
An account created without a username logs in with the address it signed up with, which is its own permanent login ID and keeps working even after the email is changed. See E-Mail and username for when email login starts, and the one case where it is not enabled.
Two-Step Login
When a user has turned on two-step login with an authenticator app, login() rejects with the code MFA_REQUIRED after checking the password, and verifyMFA() finishes the login with the 6 digit code from the app. See Two-Step Login (MFA).
Auto Login
By default, once user login to your website, their login session is maintained until they logout.
The session is kept up by the SDK: the sign-in token is refreshed in the background when it nears its end, and a refresh that gets no answer because the network is down leaves the session as it is, so a user whose connection drops for a while is still signed in when it returns (the request that needed the token fails with the code NETWORK_ERROR, as any request does without network, and the next one refreshes again). The session ends only when the user logs out or the server answers a refresh with a rejection: an expired or revoked refresh token, or a deleted account. A page that loads while the network is down and the stored token has already expired starts with no user (onLogin receives null), and the session is back on the next page load with network.
When several requests need a fresh token at the same moment, the SDK refreshes it once and they all wait for that one refresh. When the stored token has already expired as the page loads, it is refreshed once, not twice.
To ensure that users' sessions are destroyed when they leave your website, you can set options.autoLogin to false in the third argument when initializing Skapi.
const options = {
autoLogin: false, // session is destroyed when the user leaves; omit or set true (the default) to keep the session.
};
//Set the third argument as options
const skapi = new Skapi("<Project ID>", options);Logout
The logout() method logs the user out from the project. On an anonymous session (see Anonymous Login) it also deletes the temporary account at once.
A logout always wins over a token refresh that is still running. If the user logs out while the SDK is refreshing the sign-in token in the background, the refresh does not sign them back in. A request that was still waiting for that token ends with the error User login is required. (code INVALID_REQUEST).
<form onsubmit="skapi.logout(event)" action="page_to_show_after_logout.html">
<input type="submit" value="Logout" />
</form>skapi.logout().then((res) => {
console.log(res); // 'SUCCESS: The user has been logged out.'
window.location.replace("page_to_show_after_logout.html");
});Global Logout
You can let the users logout and invalidate all tokens across all the users devices by setting params.global to true.
If the other devices cannot be signed out (for example the network is down), the user is still logged out on this device, and logout() rejects with the error so you can tell the user that the other devices may still be signed in.
<form onsubmit="skapi.logout(event)" action="page_to_show_after_logout.html">
<input type="checkbox" name="global" checked />
<input type="submit" value="Logout" />
</form>skapi.logout({ global: true }).then((res) => {
console.log(res); // 'SUCCESS: The user has been logged out.'
window.location.replace("page_to_show_after_logout.html");
});For more detailed information on all the parameters and options available with the logout() method, please refer to the API Reference below:
logout(params?): Promise<'SUCCESS: The user has been logged out.'>
Listening to Login / Logout Status
You can listen to the updates of the user's login state by setting a callback function in the option.eventListener.onLogin option argument of the constructor argument in Skapi.
The onLogin callback is triggered in the following cases:
- Skapi initializes with the user's current authentication state.
- User logs in or logs out.
- User loses their session because the server rejected the token refresh (an expired or revoked refresh token, a deleted account). A refresh that fails for lack of network does not end the session and does not trigger the callback.
If the user is logged in, the callback receives the UserProfile object; otherwise, it receives null.
const options = {
eventListener: {
onLogin: (profile) => {
console.log(profile); // is null when user is logged out, User's information object when logged in.
},
},
};
const skapi = new Skapi("<Project ID>", options);You can also add multiple event listeners to the onLogin event after the Skapi object has been initialized.
skapi.onLogin = (profile) => {
console.log(profile); // null when user is logged out, User's information object when logged in.
};This handler is useful for updating the UI when the user logs in, logs out.
If your onLogin callback throws, the error is printed to the console. It does not stop the other listeners, and it does not stop the login, logout or token refresh that called it.
