Sign In with Email and Password

Sign In with Email and Password is enabled by default on all projects.

Sign Up

To sign up a new user, use signUpEmailPassword with a valid email and password.

Without Email Verification

When email verification is disabled, sign-up returns a session directly:

const response = await nhost.auth.signUpEmailPassword({
  email: 'joe@example.com',
  password: 'secret-password',
});

// response.body.session contains the access + refresh tokens

With Email Verification

By default, newly registered users must verify their email before they can sign in. To change this, navigate to Settings -> Sign-In Methods -> Email and Password and set Require Verified Emails.

When email verification is enabled (the default), pass a codeChallenge for PKCE so the verification link can securely establish a session:

import { generatePKCEPair } from '@nhost/nhost-js/auth';

// Generate PKCE pair and store verifier for later
const { verifier, challenge } = await generatePKCEPair();
localStorage.setItem('nhost_pkce_verifier', verifier);

await nhost.auth.signUpEmailPassword({
  email: 'joe@example.com',
  password: 'secret-password',
  options: {
    redirectTo: `${window.location.origin}/verify`,
  },
  codeChallenge: challenge,
});

Note

A newly registered user will receive an email with a verification link. Clicking the link redirects to your app with an authorization code that must be exchanged for a session.

Email Verification

The email verification email is sent automatically when the user signs up but, you can manually resend the verification email:

import { generatePKCEPair } from '@nhost/nhost-js/auth';

const { verifier, challenge } = await generatePKCEPair();
localStorage.setItem('nhost_pkce_verifier', verifier);

await nhost.auth.userEmailSendVerificationEmail({
  email: 'joe@example.com',
  options: {
    redirectTo: `${window.location.origin}/verify`,
  },
  codeChallenge: challenge,
});

Tip

It is possible to customize these automatic emails, learn how to here.

Sign In

After a user is registered and verified, they can sign in. Email/password sign-in returns a session directly without PKCE.

await nhost.auth.signInEmailPassword({
  email: 'joe@example.com',
  password: 'secret-password',
});

Note

Email/password sign-in also supports Multi-Factor Authentication (MFA). When MFA is enabled, the sign-in response returns a ticket instead of a session, and the user must provide a TOTP code to complete authentication.

Password Reset

Users can request a password reset email. The reset flow uses PKCE to securely establish a session so the user can set a new password.

import { generatePKCEPair } from '@nhost/nhost-js/auth';

const { verifier, challenge } = await generatePKCEPair();
localStorage.setItem('nhost_pkce_verifier', verifier);

await nhost.auth.userPasswordReset({
  email: 'joe@example.com',
  options: {
    redirectTo: `${window.location.origin}/verify`,
  },
  codeChallenge: challenge,
});

After the user clicks the reset link and the authorization code is exchanged for a session, the user can set a new password:

await nhost.auth.changePassword({
  newPassword: 'new-secret-password',
});

Change Password

An authenticated user can change their password directly:

await nhost.auth.changePassword({
  newPassword: 'new-secret-password',
});

A user who has completed a password reset flow can also set a new password using the session established by the reset link.

Change Email

An authenticated user can request an email change. A verification email is sent to the new address using PKCE to securely confirm the change.

import { generatePKCEPair } from '@nhost/nhost-js/auth';

const { verifier, challenge } = await generatePKCEPair();
localStorage.setItem('nhost_pkce_verifier', verifier);

await nhost.auth.userEmailChange({
  newEmail: 'new-joe@example.com',
  options: {
    redirectTo: `${window.location.origin}/verify`,
  },
  codeChallenge: challenge,
});