Passwords

Password authentication and management

Passwords API

The accounts-password package provides secure password-based authentication.

Source: packages/accounts-password/

Client Methods

Meteor.loginWithPassword()

Log the user in with a password.

Locus: Client

selector · string | object · required

Either a string interpreted as a username or an email; or an object with a single key: email, username or id. Username or email match in a case insensitive manner.

password · string · required

The user’s password.

callback · function

Optional callback. Called with no arguments on success, or with a single Error argument on failure.

// Login with username
Meteor.loginWithPassword('johndoe', 'password123', (error) => {
  if (error) {
    alert('Login failed: ' + error.reason);
  } else {
    console.log('Logged in successfully');
  }
});

// Login with email
Meteor.loginWithPassword('[e-mail]', 'password123', callback);

// Login with object selector
Meteor.loginWithPassword(
  { username: 'johndoe' },
  'password123',
  callback
);

Accounts.changePassword()

Change the current user’s password. Must be logged in.

Locus: Client

oldPassword · string · required

The user’s current password. This is not sent in plain text over the wire.

newPassword · string · required

A new password for the user. This is not sent in plain text over the wire.

callback · function

Optional callback. Called with no arguments on success, or with a single Error argument on failure.

Accounts.changePassword('oldPassword', 'newPassword', (error) => {
  if (error) {
    alert('Password change failed: ' + error.reason);
  } else {
    alert('Password changed successfully');
  }
});

Accounts.forgotPassword()

Request a forgot password email.

Locus: Client

options · object · required

Must contain email field.

email · string · required

The email address to send a password reset link.

Accounts.forgotPassword(
  { email: '[e-mail]' },
  (error) => {
    if (error) {
      alert('Error: ' + error.reason);
    } else {
      alert('Password reset email sent');
    }
  }
);

Accounts.resetPassword()

Reset the password for a user using a token received in email. Logs the user in afterwards if the user doesn’t have 2FA enabled.

Locus: Client

token · string · required

The token retrieved from the reset password URL.

newPassword · string · required

A new password for the user. This is not sent in plain text over the wire.

callback · function

Optional callback. Called with no arguments on success, or with a single Error argument on failure.

// Extract token from URL
const token = FlowRouter.getParam('token');

Accounts.resetPassword(token, 'newPassword123', (error) => {
  if (error) {
    alert('Password reset failed: ' + error.reason);
  } else {
    alert('Password reset successful');
    FlowRouter.go('/');
  }
});

Accounts.verifyEmail()

Marks the user’s email address as verified. Logs the user in afterwards if the user doesn’t have 2FA enabled.

Locus: Client

token · string · required

The token retrieved from the verification URL.

const token = FlowRouter.getParam('token');

Accounts.verifyEmail(token, (error) => {
  if (error) {
    alert('Verification failed: ' + error.reason);
  } else {
    alert('Email verified successfully');
  }
});

Server Methods

Accounts.setPasswordAsync()

Forcibly change the password for a user.

Locus: Server

userId · string · required

The id of the user to update.

newPassword · string · required

A new password for the user.

options · object

Optional options object.

logout · boolean

Logout all current connections with this userId (default: true)

// Change user password and log them out
await Accounts.setPasswordAsync(userId, 'newSecurePassword');

// Change password but keep them logged in
await Accounts.setPasswordAsync(userId, 'newPassword', { 
  logout: false 
});

Accounts.sendResetPasswordEmail()

Send an email with a link the user can use to reset their password.

Locus: Server

userId · string · required

The id of the user to send email to.

email · string

Optional. Which address of the user’s to send the email to. This address must be in the user’s emails list. Defaults to the first email in the list.

extraTokenData · object

Optional additional data to be added into the token record.

extraParams · object

Optional additional params to be added to the reset url.

Returns: Promise<{email, user, token, url, options}>

await Accounts.sendResetPasswordEmail(userId, '[e-mail]');

// With extra params
await Accounts.sendResetPasswordEmail(
  userId,
  '[e-mail]',
  null,
  { source: 'admin-panel' }
);

Accounts.sendEnrollmentEmail()

Send an email with a link the user can use to set their initial password.

Locus: Server

userId · string · required

The id of the user to send email to.

email · string

Optional. Which address of the user’s to send the email to.

// Create user without password
const userId = await Accounts.createUserAsync({
  email: '[e-mail]',
  profile: { name: 'New User' }
});

// Send enrollment email
await Accounts.sendEnrollmentEmail(userId);

Accounts.sendVerificationEmail()

Send an email with a link the user can use verify their email address.

Locus: Server

userId · string · required

The id of the user to send email to.

email · string

Optional. Which address of the user’s to send the email to. This address must be in the user’s emails list. Defaults to the first unverified email in the list.

await Accounts.sendVerificationEmail(userId);

Email Management (Server)

Accounts.addEmailAsync()

Add an email address for a user.

Locus: Server

userId · string · required

The ID of the user to update.

newEmail · string · required

A new email address for the user.

verified · boolean

Optional - whether the new email address should be marked as verified. Defaults to false.

await Accounts.addEmailAsync(userId, '[e-mail]', false);

Accounts.removeEmail()

Remove an email address for a user.

Locus: Server

userId · string · required

The ID of the user to update.

email · string · required

The email address to remove.

await Accounts.removeEmail(userId, '[e-mail]');

Accounts.replaceEmailAsync()

Replace an email address for a user.

Locus: Server

userId · string · required

The ID of the user to update.

oldEmail · string · required

The email address to replace.

newEmail · string · required

The new email address to use.

verified · boolean

Optional - whether the new email address should be marked as verified. Defaults to false.

await Accounts.replaceEmailAsync(
  userId,
  '[e-mail]',
  '[e-mail]',
  true
);

Password Security Configuration

Configure password hashing algorithms and security parameters.

Accounts.config({
  // bcrypt configuration (default)
  bcryptRounds: 10,
  
  // Or use argon2 (more secure)
  argon2Enabled: true,
  argon2Type: 'argon2id', // 'argon2i', 'argon2d', or 'argon2id'
  argon2TimeCost: 2,
  argon2MemoryCost: 19456, // in KiB (19MB)
  argon2Parallelism: 1
});

Complete Example: Password Reset Flow

// Server: Configure email URLs
import { Accounts } from 'meteor/accounts-base';

Accounts.urls.resetPassword = (token, extraParams) => {
  return Meteor.absoluteUrl(`reset-password/${token}`);
};

// Server: Send reset email
Meteor.methods({
  async sendPasswordReset(email) {
    const user = await Accounts.findUserByEmail(email);
    if (!user) {
      throw new Meteor.Error('not-found', 'User not found');
    }
    await Accounts.sendResetPasswordEmail(user._id, email);
  }
});

// Client: Request password reset
Template.forgotPassword.events({
  'submit form'(event) {
    event.preventDefault();
    const email = event.target.email.value;
    
    Meteor.call('sendPasswordReset', email, (error) => {
      if (error) {
        alert(error.reason);
      } else {
        alert('Password reset email sent');
      }
    });
  }
});

// Client: Reset password page
Template.resetPassword.onCreated(function() {
  this.token = FlowRouter.getParam('token');
});

Template.resetPassword.events({
  'submit form'(event, template) {
    event.preventDefault();
    const newPassword = event.target.password.value;
    
    Accounts.resetPassword(template.token, newPassword, (error) => {
      if (error) {
        alert('Reset failed: ' + error.reason);
      } else {
        alert('Password reset successful');
        FlowRouter.go('/');
      }
    });
  }
});