Docs Menu

Docs HomeDevelop ApplicationsAtlas Device SDK

Manage Email/Password Users - Node.js SDK

On this page

  • Register a New User Account
  • Confirm a New User's Email Address
  • Complete a User Confirmation
  • Retry User Confirmation Methods
  • Resend a Confirmation Email
  • Retry a User Confirmation Function
  • Reset a User's Password
  • Send a Password Reset Email
  • Call a Password Reset Function

To register a new email/password user, pass the user's email address and desired password to EmailPasswordAuth.registerUser(). The email address must not be associated with another email/password user and the password must be between 6 and 128 characters.

await app.emailPasswordAuth.registerUser({
email: "someone@example.com",
password: "Pa55w0rd!",
});

Note

Confirm New Users

You must confirm a new user's email address before they can log in to your app.

New users must confirm that they own their email address before they can log in to your app unless the provider is configured to automatically confirm new users.

You need a valid token and tokenId for a registered user in order to confirm them and allow them to log in. These values are available in different places depending on the provider configuration:

  • If the provider is set to send a confirmation email, the token and tokenId values are included as query parameters in the Email Confirmation URL.

  • If the provider is set to run a confirmation function, the token and tokenId values are passed to the function as arguments.

To confirm a registered user, pass a valid token and tokenId to EmailPasswordAuth.confirmUser().

const token = "someToken";
const tokenId = "someTokenId";
try {
await app.emailPasswordAuth.confirmUser({ token, tokenId });
// User email address confirmed.
console.log("Successfully confirmed user.");
} catch (err) {
console.log(`User confirmation failed: ${err}`);
}

The SDK provides methods to resend user confirmation emails or retry custom confirmation methods.

If the provider is configured to send a confirmation email, Atlas App Services automatically sends a confirmation email when a user registers. The email contains a link to the configured Email Confirmation URL with a token that is valid for 30 minutes. If a user does not follow the link and confirm within that period, they must request a new confirmation email.

To send a new confirmation email to a user, pass their email address to EmailPasswordAuth.resendConfirmationEmail().

const email = "someone@example.com";
await app.emailPasswordAuth.resendConfirmation({ email });

To re-run your custom confirmation function, call the retryCustomConfirmation() method with the user's email address:

const email = "someone@example.com";
await app.emailPasswordAuth.retryCustomConfirmation({ email });

Resetting a user's password is a multi-step process.

  1. In your client app, you provide a UI for the user to reset their password. Your App Services App can then send an email or run a custom function to confirm the user's identity.

  2. After confirming the user's identity, you can complete the password reset request.

  3. After the password reset is complete, the user can log in using the new password.

Select your preferred password reset method by going to:

  1. Your Atlas App Services App

  2. Authentication

  3. Authentication Providers

  4. Email/Password - and press the EDIT button

To send password reset emails to confirm the user's identity, you must configure your App to send a password reset email.

To begin the password reset process, call EmailPasswordAuth.sendResetPasswordEmail() with the user's email. The email contains a link to the configured Password Reset URL. The user must visit this URL within 30 minutes to confirm the reset.

const email = "someone@example.com";
await app.emailPasswordAuth.sendResetPasswordEmail({ email });

After the user has visited the URL from the password reset email, call EmailPasswordAuth.resetPassword() with the user's email, the new password, and the token and tokenId provided in the unique URL.

await app.emailPasswordAuth.resetPassword({
password: "newPassw0rd",
token,
tokenId,
});

If the user does not visit the URL from the password reset email within 30 minutes, the token and tokenId expire. You must begin the password reset process again.

When you configure your app to run a password reset function, you define the function that should run when you call EmailPasswordAuth.callResetPasswordFunction().

This function can take a username, a password, and any number of additional arguments. You can use these arguments to specify details like security question answers or other challenges that the user should pass to successfully complete a password reset.

You might prefer to use a custom password reset function when you want to define your own password reset flows. For example, you might send a custom password reset email from a specific domain. Or you might use a service other than email to confirm the user's identity.

On the App Services side, you define the custom password reset function that runs when you call this method. That function can return one of three possible statuses:

  • fail

  • pending

  • success

A fail status is treated as an error by the SDK. The SDK callResetPasswordFunction() does not take return values, so it does not return a pending or success status to the client.

Your App Services password reset function may return pending if you want the user to take some additional step to confirm their identity. However, that return value is not passed to the SDK's callResetPasswordFunction(), so your client app must implement its own logic to handle a pending status.

const email = "someone@example.com";
// The new password to use
const password = "newPassw0rd";
// Additional arguments for the reset function
const args = [];
await app.emailPasswordAuth.callResetPasswordFunction(
{ email, password },
args
);

Your server-side function might send an email using a custom email provider. Or you may use SMS to confirm the user's identity via text message.

You have access to a token and tokenId in the App Services password reset function context. If you pass this information from your App Services password reset function, you can pass these values back to your app using platform-specific deep linking or universal links. Then, your client application can call EmailPasswordAuth.resetPassword() to complete the password reset flow.

await app.emailPasswordAuth.resetPassword({
password: "newPassw0rd",
token,
tokenId,
});

If your App Services password reset function does additional validation within the function, or if you have validated the user's identity prior to attempting to reset the password, you may configure the App Services function to return success. However, that return value is not passed to the SDK's callResetPasswordFunction(), so your client app must implement its own logic to handle a success status.

Calling the function in this example performs the entire password reset process.

const email = "someone@example.com";
// The new password to use
const password = "newPassw0rd";
// Additional arguments for the reset function
const args = [];
await app.emailPasswordAuth.callResetPasswordFunction(
{ email, password },
args
);
←  User Metadata - Node.js SDKMulti-User Applications - Node.js SDK →