# API (/docs/concepts/api)

了解如何在服务器上调用 Better Auth API 端点，传递 body、headers 和 query 参数，获取响应 headers，以及处理错误。



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

无论是来自插件还是核心添加到 Better Auth 的任何端点，都可以通过 `api` 对象访问。

## 在服务器上调用 API 端点 [#在服务器上调用-api-端点]

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

```ts title="server.ts"
import { betterAuth } from "better-auth";
import { headers } from "next/headers";

export const auth = betterAuth({
    //...
})

// 在服务器上调用获取会话接口
await auth.api.getSession({
    headers: await headers() // 某些端点可能需要 headers
})
```

### Body、Headers、Query [#bodyheadersquery]

与客户端不同，服务器需要将值作为包含键的对象传递，`body` 对应请求体，`headers` 对应请求头，`query` 对应查询参数。

```ts title="server.ts"
import { auth } from "@/lib/auth"

await auth.api.getSession({
    headers: await headers() // 包含用户会话令牌的 headers
})

await auth.api.signInEmail({
    body: {
        email: "john@doe.com",
        password: "password"
    },
    headers: await headers() // 可选，但有助于获取用户 IP、用户代理等信息
})

await auth.api.verifyEmail({
    query: {
        token: "my_token"
    }
})
```

<Callout>
  Better Auth API 端点建立在 [better-call](https://github.com/bekacru/better-call) 之上，这是一个小型 Web 框架，允许你像调用普通函数一样调用 REST API 端点，并使我们能够轻松地从服务器端推断客户端类型。
</Callout>

### 获取 `headers` 和 `Response` 对象 [#获取-headers-和-response-对象]

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

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

#### 获取 `headers` [#获取-headers]

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

```ts title="server.ts"
import { auth } from "@/lib/auth"

const { headers, response } = await auth.api.signUpEmail({
	returnHeaders: true,
	body: {
		email: "john@doe.com",
		password: "password",
		name: "John Doe",
	},
});
```

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

```ts
const cookies = headers.getSetCookie();
const customHeader = headers.get("x-custom-header");
```

#### 获取 `Response` 对象 [#获取-response-对象]

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

```ts title="server.ts"
import { auth } from "@/lib/auth"

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

### 错误处理 [#错误处理]

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

```ts title="server.ts"
import { auth } from "@/lib/auth"
import { APIError, isAPIError } from "better-auth/api";

try {
    await auth.api.signInEmail({
        body: {
            email: "",
            password: ""
        }
    })
} catch (error) {
    if (isAPIError(error)) {
        console.log(error.message, error.status)
    }
}
```