Skip to main content

Email & Password

Email and password is the built-in way to sign in to an auth collection. It is on by default: a collection's authRule decides who may sign in, and null turns sign-in off.

Sign up​

signUp creates the account and signs it in, in one request. The collection's createRule must allow it; "" lets anyone sign up.

const { record } = await nb.collection("users").signUp(
  {
    email: "ann@example.com",
    password: "a long password",
    passwordConfirm: "a long password",
    name: "Ann",
  },
  { cookie: true },
);

signUp returns null when the account was created but may not sign in yet, such as before verifying its email.

Sign in​

await nb
  .collection("users")
  .signInWithPassword("ann@example.com", "a long password", { cookie: true });
  • With cookie: true, the session lives in an HttpOnly cookie, the right choice for Next.js apps. Without it, the response returns a Bearer token, for mobile apps and scripts. See Sessions and cookies.
  • The identity is matched against the collection's identityFields, by default ["email"], regardless of case.
  • Wrong credentials throw a ClientError with status 400 and the same message whether or not the account exists.

Sign out​

await nb.signOut();

Signing out deletes the session on the server, so its token stops working at once.

Change the password​

A signed-in user changes their password by updating their own record with the current one:

await nb.collection("users").update(user.id, {
  oldPassword: "a long password",
  password: "a new long password",
  passwordConfirm: "a new long password",
});

Every other session of the account ends; the one that made the change stays signed in. A user who forgot their password uses a password reset instead.

Require a verified email​

To let only verified accounts sign in, set the collection's authRule:

await superuser.collections.update("users", { authRule: "verified = true" });

Unverified accounts then get a 403 when they sign in, and signUp returns null. Send them a link with email verification.

Build a sign-in page​

listAuthMethods tells a sign-in page what to ask for:

const { password } = await nb.collection("users").listAuthMethods();
// { enabled: true, identityFields: ["email"] }

Protections​

  • Passwords are hashed with scrypt, and hashes are upgraded on sign-in when the parameters are raised.
  • Failed sign-ins are counted per account. After too many, sign-in is blocked for a while, and a password reset lifts the block.
  • Responses take the same time and give the same error whether or not the account exists.