email & password authentication

20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Email verification sendVerificationEmail function parameters

The sendVerificationEmail function accepts a data object with properties: user (the user object containing the email address), url (the verification URL the user must click to verify their email), and token (the verification token used to complete the email verification to be used when implementing a custom verification URL). It also accepts a request object as the second parameter.

Email verification sendOnSignUp option

Setting emailVerification.sendOnSignUp to true automatically sends a verification email when a user signs up. For social logins, email verification status is read from the SSO provider.

Email verification requireEmailVerification behavior

When emailAndPassword.requireEmailVerification is enabled, users must verify their email before they can log in. Every time a user tries to sign in, sendVerificationEmail is called. This only works if sendVerificationEmail is implemented, sendOnSignIn is set to true, and the user is trying to sign in with email and password.

Email verification error handling for unverified emails

When a user tries to sign in without verifying their email and requireEmailVerification is enabled, the API returns a 403 status error. This can be caught in the onError callback of authClient.signIn.email() to display a verification prompt to the user.

Manually trigger email verification with sendVerificationEmail client method

The authClient.sendVerificationEmail() method accepts email and callbackURL properties. The callbackURL is the redirect URL after verification is complete.

Manual email verification with verifyEmail client method

The authClient.verifyEmail() method accepts a query object with a token property. This allows custom verification URLs where the token is passed and verified.

Auto sign-in after email verification

Setting emailVerification.autoSignInAfterVerification to true automatically signs in the user after they successfully verify their email.

Password reset sendResetPassword function parameters

The sendResetPassword function in emailAndPassword configuration accepts a data object with properties: user (the user object containing the email address), url (the password reset URL the user must click), and token (the reset token used to complete password reset). It also accepts a request object as the second parameter.

Email sending performance recommendation to avoid timing attacks

When implementing sendVerificationEmail and sendResetPassword functions, avoid awaiting the email sending to prevent timing attacks. On serverless platforms, use waitUntil or similar mechanisms to ensure the email is sent.

Email is required for all users in Better Auth

Email is a key part of Better Auth and is required for all users regardless of their authentication method.

Better Auth works with any transactional email provider

Better Auth works with any transactional email provider, giving full control over how authentication emails are delivered. Users need to set up their preferred provider and implement the email sending functions.

Social login email verification behavior

When sendOnSignUp is enabled and a user logs in with an SSO provider that does not claim the email as verified, Better Auth will dispatch a verification email. However, the verification is not required to login even when requireEmailVerification is enabled.

Email verification example with sendVerificationEmail implementation

```ts import { betterAuth } from 'better-auth'; import { sendEmail } from './email'; export const auth = betterAuth({ emailVerification: { sendVerificationEmail: async ({ user, url, token }, request) => { void sendEmail({ to: user.email, subject: 'Verify your email address', text: `Click the link to verify your email: ${url}` }) } } }) ``` This example shows how to implement email verification with a custom email provider function.

Email verification with sendOnSignUp configuration example

```ts import { betterAuth } from 'better-auth'; export const auth = betterAuth({ emailVerification: { sendOnSignUp: true } }) ``` This example shows how to enable automatic verification email sending during sign-up.

Require email verification configuration example

```ts import { betterAuth } from "better-auth"; import { sendEmail } from './email'; export const auth = betterAuth({ emailVerification: { sendVerificationEmail: async ({ user, url }) => { void sendEmail({ to: user.email, subject: "Verify your email address", text: `Click the link to verify your email: ${url}`, }); }, sendOnSignIn: true, }, emailAndPassword: { requireEmailVerification: true, }, }); ``` This example shows how to require email verification before sign-in.

Error handling for unverified email sign-in example

```ts await authClient.signIn.email({ email: "email@example.com", password: "password" }, { onError: (ctx) => { if(ctx.error.status === 403) { alert("Please verify your email address") } alert(ctx.error.message) } }) ``` This example shows how to handle the 403 error when a user tries to sign in with an unverified email.

Manual email verification trigger example

```ts await authClient.sendVerificationEmail({ email: "user@email.com", callbackURL: "/" }) ``` This example shows how to manually trigger email verification with a callback URL.

Manual email verification with token example

```ts await authClient.verifyEmail({ query: { token: "" } }) ``` This example shows how to verify an email using a token for custom verification URLs.

Auto sign-in after verification configuration example

```ts import { betterAuth } from "better-auth"; const auth = betterAuth({ emailVerification: { autoSignInAfterVerification: true } }) ``` This example shows how to enable automatic sign-in after successful email verification.

Password reset configuration example

```ts import { betterAuth } from 'better-auth'; import { sendEmail } from './email'; export const auth = betterAuth({ emailAndPassword: { enabled: true, sendResetPassword: async ({ user, url, token }, request) => { void sendEmail({ to: user.email, subject: 'Reset your password', text: `Click the link to reset your password: ${url}` }) } } }) ``` This example shows how to implement password reset email functionality.

Give your agent this brain