API

当你创建一个新的 Better Auth实例时，它会提供一个 api 对象。这个对象暴露了你的 Better Auth 实例中所有可用的端点。你可以使用它在服务器端与 Better Auth 进行交互。

无论是来自插件还是核心功能的任何端点，都可以通过 api 对象访问。

在服务器端调用API端点

要在服务器端调用API端点，导入你的 auth 实例并使用 api 对象调用端点。

server.ts
import { betterAuth } from "better-auth";
import { headers } from "next/headers";
 
export const auth = betterAuth({
    //...
})
 
// 在服务器端调用获取会话
await auth.api.getSession({
    headers: headers() // 某些端点可能需要请求头
})

请求体、请求头和查询参数

与客户端不同，服务器端需要将值作为对象传递，其中 body 表示请求体，headers 表示请求头，query 表示查询参数。

server.ts
await auth.api.getSession({
    headers: headers()
})
 
await auth.api.signInEmail({
    body: {
        email: "[email protected]",
        password: "password"
    },
    headers: headers() // 可选，但获取用户 IP、用户代理等信息时很有用
})
 
await auth.api.verifyEmail({
    query: {
        token: "my_token"
    }
})

Better Auth 的 API 端点是基于 better-call 构建的。这是一个轻量级的 Web 框架，它让你可以像调用普通函数一样调用 REST API 端点，并允许我们轻松地从服务器推断客户端类型。

获取 headers 和 Response 对象

当你在服务器端调用 API 端点时，它会直接返回一个标准的 JavaScript 对象或数组，因为这只是一个普通的函数调用。

但有时你可能想要获取 headers 或 Response 对象。例如，当你需要获取 cookies 或请求头时。

获取 headers

要获取 headers，你可以向端点传递 returnHeaders 选项。

const { headers, response } = await auth.api.signUpEmail({
    returnHeaders: true,
    body: {
        email: "[email protected]",
        password: "password",
        name: "John Doe",
    },
});

headers 将是一个 Headers 对象。你可以用它来获取 cookies 或请求头。

const cookies = headers.get("set-cookie");
const headers = headers.get("x-custom-header");

获取 Response 对象

要获取 Response 对象，你可以向端点传递 asResponse 选项。

server.ts
const response = await auth.api.signInEmail({
    body: {
        email: "",
        password: ""
    },
    asResponse: true
})

错误处理

当你在服务器端调用 API 端点时，如果请求失败，它会抛出一个错误。你可以捕获这个错误并根据需要处理它。错误实例是 APIError 的实例。

server.ts
import { APIError } from "better-auth/api";
 
try {
    await auth.api.signInEmail({
        body: {
            email: "",
            password: ""
        }
    })
} catch (error) {
    if (error instanceof APIError) {
        console.log(error.message, error.status)
    }
}

基本用法

Better Auth入门指南

CLI

用于管理项目的内置命令行工具

On this page