电子邮件 OTP

电子邮件 OTP 插件允许用户使用发送到其电子邮件地址的一次性密码 (OTP) 来登录、验证其电子邮件或重置密码。

安装

将插件添加到您的 auth 配置中

将 emailOTP 插件添加到您的 auth 配置中，并实现 sendVerificationOTP() 方法。

auth.ts

import { betterAuth } from "better-auth"
import { emailOTP } from "better-auth/plugins"

export const auth = betterAuth({
    // ... other config options
    plugins: [
        emailOTP({ 
            async sendVerificationOTP({ email, otp, type }) { 
                if (type === "sign-in") { 
                    // Send the OTP for sign in
                } else if (type === "email-verification") { 
                    // Send the OTP for email verification
                } else { 
                    // Send the OTP for password reset
                } 
            }, 
        }) 
    ]
})

添加客户端插件

auth-client.ts

import { createAuthClient } from "better-auth/client"
import { emailOTPClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [
        emailOTPClient()
    ]
})

使用方法

发送 OTP

使用 sendVerificationOtp() 方法向用户的电子邮件地址发送 OTP。

POST

/email-otp/send-verification-otp

const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user@example.com", // required
    type: "sign-in", // required
});

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。`sign-in`、`email-verification` 或 `forget-password`。	`"email-verification" \| "sign-in" \| "forget-password"`

POST

/email-otp/send-verification-otp

const data = await auth.api.sendVerificationOTP({
    body: {
        email: "user@example.com", // required
        type: "sign-in", // required
    },
});

const data = await auth.api.sendVerificationOTP({    body: {        email: "user@example.com", // required        type: "sign-in", // required    },});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。`sign-in`、`email-verification` 或 `forget-password`。	`"email-verification" \| "sign-in" \| "forget-password"`

检查 OTP（可选）

使用 checkVerificationOtp() 方法检查 OTP 是否有效。

POST

/email-otp/check-verification-otp

const { data, error } = await authClient.emailOtp.checkVerificationOtp({
    email: "user@example.com", // required
    type: "sign-in", // required
    otp: "123456", // required
});

const { data, error } = await authClient.emailOtp.checkVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required    otp: "123456", // required});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。`sign-in`、`email-verification` 或 `forget-password`。	`"email-verification" \| "sign-in" \| "forget-password"`
`otp`	发送到电子邮件的 OTP。	`string`

POST

/email-otp/check-verification-otp

const data = await auth.api.checkVerificationOTP({
    body: {
        email: "user@example.com", // required
        type: "sign-in", // required
        otp: "123456", // required
    },
});

const data = await auth.api.checkVerificationOTP({    body: {        email: "user@example.com", // required        type: "sign-in", // required        otp: "123456", // required    },});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。`sign-in`、`email-verification` 或 `forget-password`。	`"email-verification" \| "sign-in" \| "forget-password"`
`otp`	发送到电子邮件的 OTP。	`string`

使用 OTP 登录

要使用 OTP 登录，请使用 sendVerificationOtp() 方法向用户的电子邮件地址发送“sign-in” OTP。

POST

/email-otp/send-verification-otp

const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user@example.com", // required
    type: "sign-in", // required
});

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"sign-in"`

POST

/email-otp/send-verification-otp

const data = await auth.api.sendVerificationOTP({
    body: {
        email: "user@example.com", // required
        type: "sign-in", // required
    },
});

const data = await auth.api.sendVerificationOTP({    body: {        email: "user@example.com", // required        type: "sign-in", // required    },});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"sign-in"`

一旦用户提供 OTP，您可以使用 signIn.emailOtp() 方法登录用户。

POST

/sign-in/email-otp

const { data, error } = await authClient.signIn.emailOtp({
    email: "user@example.com", // required
    otp: "123456", // required
});

const { data, error } = await authClient.signIn.emailOtp({    email: "user@example.com", // required    otp: "123456", // required});

Prop	Description	Type
`email`	登录的电子邮件地址。	`string`
`otp`	发送到电子邮件的 OTP。	`string`

POST

/sign-in/email-otp

const data = await auth.api.signInEmailOTP({
    body: {
        email: "user@example.com", // required
        otp: "123456", // required
    },
});

const data = await auth.api.signInEmailOTP({    body: {        email: "user@example.com", // required        otp: "123456", // required    },});

Prop	Description	Type
`email`	登录的电子邮件地址。	`string`
`otp`	发送到电子邮件的 OTP。	`string`

如果用户未注册，他们将被自动注册。如果您想防止这种情况，可以在选项中将 disableSignUp 传递为 true。

使用 OTP 验证电子邮件

要使用 OTP 验证用户的电子邮件地址，请使用 sendVerificationOtp() 方法向用户的电子邮件地址发送“email-verification” OTP。

POST

/email-otp/send-verification-otp

const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user@example.com", // required
    type: "email-verification", // required
});

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "email-verification", // required});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"email-verification"`

POST

/email-otp/send-verification-otp

const data = await auth.api.sendVerificationOTP({
    body: {
        email: "user@example.com", // required
        type: "email-verification", // required
    },
});

const data = await auth.api.sendVerificationOTP({    body: {        email: "user@example.com", // required        type: "email-verification", // required    },});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"email-verification"`

一旦用户提供 OTP，请使用 verifyEmail() 方法完成电子邮件验证。

POST

/email-otp/verify-email

const { data, error } = await authClient.emailOtp.verifyEmail({
    email: "user@example.com", // required
    otp: "123456", // required
});

const { data, error } = await authClient.emailOtp.verifyEmail({    email: "user@example.com", // required    otp: "123456", // required});

Prop	Description	Type
`email`	要验证的电子邮件地址。	`string`
`otp`	要验证的 OTP。	`string`

POST

/email-otp/verify-email

const data = await auth.api.verifyEmailOTP({
    body: {
        email: "user@example.com", // required
        otp: "123456", // required
    },
});

const data = await auth.api.verifyEmailOTP({    body: {        email: "user@example.com", // required        otp: "123456", // required    },});

Prop	Description	Type
`email`	要验证的电子邮件地址。	`string`
`otp`	要验证的 OTP。	`string`

使用 OTP 重置密码

要使用 OTP 重置用户的密码，请使用 forgetPassword.emailOTP() 方法向用户的电子邮件地址发送“forget-password” OTP。

POST

/forget-password/email-otp

const { data, error } = await authClient.forgetPassword.emailOtp({
    email: "user@example.com", // required
});

const { data, error } = await authClient.forgetPassword.emailOtp({    email: "user@example.com", // required});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`

POST

/forget-password/email-otp

const data = await auth.api.forgetPasswordEmailOTP({
    body: {
        email: "user@example.com", // required
    },
});

const data = await auth.api.forgetPasswordEmailOTP({    body: {        email: "user@example.com", // required    },});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`

一旦用户提供 OTP，请使用 checkVerificationOtp() 方法检查其是否有效（可选）。

POST

/email-otp/check-verification-otp

const { data, error } = await authClient.emailOtp.checkVerificationOtp({
    email: "user@example.com", // required
    type: "forget-password", // required
    otp: "123456", // required
});

const { data, error } = await authClient.emailOtp.checkVerificationOtp({    email: "user@example.com", // required    type: "forget-password", // required    otp: "123456", // required});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"forget-password"`
`otp`	发送到电子邮件的 OTP。	`string`

POST

/email-otp/check-verification-otp

const data = await auth.api.checkVerificationOTP({
    body: {
        email: "user@example.com", // required
        type: "forget-password", // required
        otp: "123456", // required
    },
});

const data = await auth.api.checkVerificationOTP({    body: {        email: "user@example.com", // required        type: "forget-password", // required        otp: "123456", // required    },});

Prop	Description	Type
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"forget-password"`
`otp`	发送到电子邮件的 OTP。	`string`

然后，使用 resetPassword() 方法重置用户的密码。

POST

/email-otp/reset-password

const { data, error } = await authClient.emailOtp.resetPassword({
    email: "user@example.com", // required
    otp: "123456", // required
    password: "new-secure-password", // required
});

const { data, error } = await authClient.emailOtp.resetPassword({    email: "user@example.com", // required    otp: "123456", // required    password: "new-secure-password", // required});

Prop	Description	Type
`email`	重置密码的电子邮件地址。	`string`
`otp`	发送到电子邮件的 OTP。	`string`
`password`	新密码。	`string`

POST

/email-otp/reset-password

const data = await auth.api.resetPasswordEmailOTP({
    body: {
        email: "user@example.com", // required
        otp: "123456", // required
        password: "new-secure-password", // required
    },
});

const data = await auth.api.resetPasswordEmailOTP({    body: {        email: "user@example.com", // required        otp: "123456", // required        password: "new-secure-password", // required    },});

Prop	Description	Type
`email`	重置密码的电子邮件地址。	`string`
`otp`	发送到电子邮件的 OTP。	`string`
`password`	新密码。	`string`

覆盖默认电子邮件验证

要覆盖默认电子邮件验证，请在选项中传递 overrideDefaultEmailVerification: true。这将使系统在触发电子邮件验证时使用电子邮件 OTP 而非默认验证链接。换句话说，用户将使用 OTP 而非点击链接来验证其电子邮件。

auth.ts

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  plugins: [
    emailOTP({
      overrideDefaultEmailVerification: true, 
      async sendVerificationOTP({ email, otp, type }) {
        // Implement the sendVerificationOTP method to send the OTP to the user's email address
      },
    }),
  ],
});

选项

sendVerificationOTP: 一个函数，用于向用户的电子邮件地址发送 OTP。该函数接收一个包含以下属性的对象：
- email: 用户的电子邮件地址。
- otp: 要发送的 OTP。
- type: 要发送的 OTP 类型。可以是 "sign-in"、"email-verification" 或 "forget-password"。
otpLength: OTP 的长度。默认为 6。
expiresIn: OTP 的过期时间（以秒为单位）。默认为 300 秒。

auth.ts

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    plugins: [
        emailOTP({
            otpLength: 8,
            expiresIn: 600
        })
    ]
})

sendVerificationOnSignUp: 一个布尔值，决定用户注册时是否发送 OTP。默认为 false。
disableSignUp: 一个布尔值，决定是否防止用户未注册时自动注册。默认为 false。
generateOTP: 一个生成 OTP 的函数。默认为随机 6 位数字。
allowedAttempts: 允许验证 OTP 的最大尝试次数。默认为 3。超过此限制后，OTP 将无效，用户需要请求一个新的。

auth.ts

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    plugins: [
        emailOTP({
            allowedAttempts: 5, // Allow 5 attempts before invalidating the OTP
            expiresIn: 300
        })
    ]
})

当最大尝试次数被超过时，verifyOTP、signIn.emailOtp、verifyEmail 和 resetPassword 方法将返回代码为 TOO_MANY_ATTEMPTS 的错误。

storeOTP: 在您的数据库中存储 OTP 的方法，无论是 encrypted、hashed 还是 plain 文本。默认为 plain 文本。

注意：这不会影响发送给用户的 OTP，它只会影响存储在您数据库中的 OTP。

或者，您可以传递自定义加密器或哈希器来在您的数据库中存储 OTP。

自定义加密器

auth.ts

emailOTP({
    storeOTP: { 
        encrypt: async (otp) => {
            return myCustomEncryptor(otp);
        },
        decrypt: async (otp) => {
            return myCustomDecryptor(otp);
        },
    }
})

自定义哈希器

auth.ts

emailOTP({
    storeOTP: {
        hash: async (otp) => {
            return myCustomHasher(otp);
        },
    }
})

开始使用

概念

认证

数据库

集成

插件

指南

参考

On this page