Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Manage Email/Password Users - Web SDK

On this page

  • Overview
  • 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
  • Complete a Password Reset

The Web SDK includes a client object that allows you to manage users associated with the Email/Password authentication provider.

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

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

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.

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 after the email is sent. If a user did not receive the initial email or didn't click the confirmation link in time, you can use the SDK to resend a confirmation email.

Alternatively, if the provider is configured to run a confirmation function, App Services automatically runs your custom Atlas Function when a user registers. If the call to the custom confirmation function fails, you can use the SDK to retry a user confirmation function.

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, call the confirmUser() method with the user's valid token and tokenId:

await app.emailPasswordAuth.confirmUser({ token, tokenId });

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

To resend the confirmation email to a user, call the resendConfirmationEmail() method with the user's email address:

const email = "someone@example.com"; // The user's email address
await app.emailPasswordAuth.resendConfirmationEmail({ email });

New in version Realm: Web v1.4.0

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

const email = "someone@example.com"; // The user's email address
await app.emailPasswordAuth.retryCustomConfirmation({ email });

If the provider is configured to send a password reset email, you can use the SDK to send a password reset email to a user. The email contains a link to the configured Password Reset URL.

// The user's email address
const email = "joe.jasper@example.com";
await app.emailPasswordAuth.sendResetPasswordEmail({ email });

If the provider is configured to run a password reset function, you can use the SDK to run the function. Pass an object with the user's email and new password. You can also include additional arguments to use in the password reset function in the App Services backend.

// The user's email address
const email = "joe.jasper@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
);

Once a user requests a password reset, either by sending a password reset email or calling a password reset function, Realm generates a pair of unique token and tokenId values that they can use to complete the password reset within 30 minutes of the initial request.

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

Example

Get the Token and TokenID

If the provider uses the built-in password reset email, the token and tokenId are included as query parameters in the password reset URL. You can access them like so:

const params = new URLSearchParams(window.location.search);
const token = params.get("token");
const tokenId = params.get("tokenId");
if (!token || !tokenId) {
throw new Error(
"You can only call resetPassword() if the user followed a confirmation email link"
);
}

Back

Authenticate a User - Web SDK

Next

Work with Multiple Users