# 一次性令牌插件 (/docs/plugins/one-time-token)

生成和验证单次使用令牌



一次性令牌（OTT）插件提供生成和验证安全的一次性会话令牌的功能。这些令牌通常用于跨域身份验证。

## 安装 [#安装]

<Steps>
  <Step>
    ### 将插件添加到您的认证配置中 [#将插件添加到您的认证配置中]

    要使用一次性令牌插件，请将其添加到您的认证配置中。

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth";
    import { oneTimeToken } from "better-auth/plugins/one-time-token"; // [!code highlight]

    export const auth = betterAuth({
        plugins: [
          oneTimeToken() // [!code highlight]
        ]
        // ... 其他认证配置
    });
    ```
  </Step>

  <Step>
    ### 添加客户端插件 [#添加客户端插件]

    接下来，在您的认证客户端实例中包含一次性令牌客户端插件。

    ```ts title="auth-client.ts"
    import { createAuthClient } from "better-auth/client"
    import { oneTimeTokenClient } from "better-auth/client/plugins" // [!code highlight]

    export const authClient = createAuthClient({
        plugins: [
            oneTimeTokenClient() // [!code highlight]
        ]
    })
    ```
  </Step>
</Steps>

## 用法 [#用法]

### 1. 生成令牌 [#1-生成令牌]

使用 `auth.api.generateOneTimeToken` 或 `authClient.oneTimeToken.generate` 方法生成令牌。

**Endpoint:** `GET /one-time-token/generate`

### Client Side

```ts
const { data, error } = await authClient.oneTimeToken.generate();
```

### Server Side

```ts
const data = await auth.api.generateOneTimeToken({
    // This endpoint requires session cookies.
    headers: await headers(),
});
```

### Type Definition

```ts
type generateOneTimeToken = {
}
```

这将返回一个附加到当前会话的 `token`，可用于验证一次性令牌。默认情况下，令牌将在 3 分钟后过期。

### 2. 验证令牌 [#2-验证令牌]

当用户点击链接或提交令牌时，在另一个 API 路由中使用 `auth.api.verifyOneTimeToken` 或 `authClient.oneTimeToken.verify` 方法进行验证。

**Endpoint:** `POST /one-time-token/verify`

### Client Side

```ts
const { data, error } = await authClient.oneTimeToken.verify({
    token: "some-token", // required, The token to verify.
});
```

### Server Side

```ts
const data = await auth.api.verifyOneTimeToken({
    body: {
        token: "some-token", // required, The token to verify.
    },
});
```

### Type Definition

```ts
type verifyOneTimeToken = {
    /**
     * The token to verify. 
     */
    token: string = "some-token"
}
```

这将返回附加到该令牌的会话。

## 选项 [#选项]

添加 `oneTimeToken` 插件时可以配置以下选项：

* **`disableClientRequest`**（boolean）：可选。如果为 `true`，令牌将仅在服务器端生成。默认值：`false`。
* **`expiresIn`**（number）：可选。令牌有效的持续时间（分钟）。默认值：`3`。

```ts
oneTimeToken({
    expiresIn: 10 // 10 分钟
})
```

* **`generateToken`**：一个自定义令牌生成函数，接收 `session` 对象和 `ctx` 作为参数。

* **`storeToken`**：可选。此选项允许您配置如何在数据库中存储令牌。

  * **`plain`**：令牌以明文存储。（默认）
  * **`hashed`**：令牌使用默认哈希算法进行哈希处理。
  * **`custom-hasher`**：一个自定义哈希函数，接收令牌并返回哈希后的令牌。

<Callout type="info">
  注意：这不会影响发送的令牌，它只会影响存储在数据库中的令牌。
</Callout>

示例：

```ts title="无哈希（默认）"
oneTimeToken({
    storeToken: "plain"
})
```

```ts title="内置哈希器"
oneTimeToken({
    storeToken: "hashed"
})
```

```ts title="自定义哈希器"
oneTimeToken({
    storeToken: {
        type: "custom-hasher",
        hash: async (token) => {
            return myCustomHasher(token);
        }
    }
})
```