API 密钥

API 密钥插件允许您为应用程序创建和管理 API 密钥。它通过验证 API 密钥来认证和授权 API 请求。

功能

创建、管理和验证 API 密钥
内置的速率限制
自定义过期时间、剩余计数和补充系统
API 密钥的元数据
自定义前缀
来自 API 密钥的会话
二级存储支持用于高性能的 API 密钥查找
多个配置用于不同类型的 API 密钥
组织拥有的 API 密钥，以及用户拥有的密钥

安装

安装插件

npm install @better-auth/api-key

将插件添加到服务器

auth.ts

import { betterAuth } from "better-auth"
import { apiKey } from "@better-auth/api-key"

export const auth = betterAuth({
    plugins: [
        apiKey() 
    ]
})

迁移数据库

运行迁移或生成架构以向数据库添加必要的字段和表。

npx auth migrate

npx auth generate

请参阅架构部分以手动添加字段。

添加客户端插件

auth-client.ts

import { createAuthClient } from "better-auth/client"
import { apiKeyClient } from "@better-auth/api-key/client"

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

使用方法

您可以查看 API 密钥插件选项。

创建 API 密钥

POST/api-key/create

Notes

您可以使用服务器方法来调整更具体的 API 密钥配置。

const { data, error } = await authClient.apiKey.create({
    configId,
    name: 'project-api-key',
    expiresIn: 60 * 60 * 24 * 7,
    organizationId: "org-id",
    prefix: 'project-api-key',
    metadata: { someKey: 'someValue' },
});

const { data, error } = await authClient.apiKey.create({    configId,    name: 'project-api-key',    expiresIn: 60 * 60 * 24 * 7,    organizationId: "org-id",    prefix: 'project-api-key',    metadata: { someKey: 'someValue' },});

Parameters

configIdstring

要使用的配置 ID。如果未提供，则使用默认配置。

namestring

API 密钥的名称。

expiresInnumber

API 密钥的过期时间（以秒为单位）。

organizationIdstring

拥有该 API 密钥的组织 ID。对于 references: "organization" 的配置是必需的。

prefixstring

API 密钥的前缀。

metadataany | null

API 密钥的元数据。

POST/api-key/create

Notes

如果在服务器上创建 API 密钥且无法访问标头，则必须传递 userId 属性（用于用户拥有的密钥）或 organizationId（用于组织拥有的密钥）。

const data = await auth.api.createApiKey({
    body: {
        configId,
        name: 'project-api-key',
        expiresIn: 60 * 60 * 24 * 7,
        userId: "user-id", // server-only
        organizationId: "org-id",
        prefix: 'project-api-key',
        remaining: 100, // server-only
        metadata: { someKey: 'someValue' },
        refillAmount: 100, // server-only
        refillInterval: 1000, // server-only
        rateLimitTimeWindow: 1000, // server-only
        rateLimitMax: 100, // server-only
        rateLimitEnabled: true, // server-only
        permissions, // server-only
    },
});

const data = await auth.api.createApiKey({    body: {        configId,        name: 'project-api-key',        expiresIn: 60 * 60 * 24 * 7,        userId: "user-id", // server-only        organizationId: "org-id",        prefix: 'project-api-key',        remaining: 100, // server-only        metadata: { someKey: 'someValue' },        refillAmount: 100, // server-only        refillInterval: 1000, // server-only        rateLimitTimeWindow: 1000, // server-only        rateLimitMax: 100, // server-only        rateLimitEnabled: true, // server-only        permissions, // server-only    },});

Parameters

configIdstring

要使用的配置 ID。如果未提供，则使用默认配置。

namestring

API 密钥的名称。

expiresInnumber

API 密钥的过期时间（以秒为单位）。

userIdstringserver

拥有该 API 密钥的用户 ID。server-only。当不使用会话标头时，这是用户拥有的密钥所必需的。

organizationIdstring

拥有该 API 密钥的组织 ID。对于 references: "organization" 的配置是必需的。

prefixstring

API 密钥的前缀。

remainingnumberserver

剩余的请求数量。server-only。

metadataany | null

API 密钥的元数据。

refillAmountnumberserver

要补充的剩余计数。server-only。

refillIntervalnumberserver

补充 API 密钥的间隔（以毫秒为单位）。server-only。

rateLimitTimeWindownumberserver

每个请求计数的时间窗口（以毫秒为单位）。一旦达到 maxRequests，请求将被拒绝，直到 timeWindow 过去，之后 timeWindow 将重置。server-only。

rateLimitMaxnumberserver

在一个窗口内允许的最大请求数。一旦达到 maxRequests，请求将被拒绝，直到 timeWindow 过去，之后 timeWindow 将重置。server-only。

rateLimitEnabledbooleanserver

是否启用速率限制。server-only。

permissionsRecord<string, string[]>server

API 密钥的权限。

API 密钥可以是用户拥有的，也可以是组织拥有的，具体取决于配置中的 references 设置。

返回结果

返回包含 key 值的 ApiKey 对象供您使用。如果发生异常，则抛出 APIError。

验证 API 密钥

const permissions = { // 需要检查的权限是可选的
  projects: ["read", "read-write"],
}

const { data, error } = await authClient.apiKey.verify({
    configId,
    key: "your_api_key_here", // required
    permissions,
});

const permissions = { // 需要检查的权限是可选的  projects: ["read", "read-write"],}const { data, error } = await authClient.apiKey.verify({    configId,    key: "your_api_key_here", // required    permissions,});

This is a server-only endpoint

const permissions = { // 需要检查的权限是可选的
  projects: ["read", "read-write"],
}

const data = await auth.api.verifyApiKey({
    body: {
        configId,
        key: "your_api_key_here", // required
        permissions,
    },
});

const permissions = { // 需要检查的权限是可选的  projects: ["read", "read-write"],}const data = await auth.api.verifyApiKey({    body: {        configId,        key: "your_api_key_here", // required        permissions,    },});

Parameters

configIdstring

用于验证的配置 ID。如果未提供，则使用默认配置。

keystringrequired

要验证的密钥。

permissionsRecord<string, string[]>

要验证的权限。可选。

结果

type Result = {
  valid: boolean;
  error: { message: string; code: string } | null;
  key: Omit<ApiKey, "key"> | null;
};

获取 API 密钥

GET/api-key/get

const { data, error } = await authClient.apiKey.get({
    query: {
        configId,
        id: "some-api-key-id", // required
    },
});

const { data, error } = await authClient.apiKey.get({    query: {        configId,        id: "some-api-key-id", // required    },});

Parameters

configIdstring

用于 API 密钥查找的配置 ID。如果未提供，则使用默认配置。

idstringrequired

API 密钥的 ID。

GET/api-key/get

const data = await auth.api.getApiKey({
    query: {
        configId,
        id: "some-api-key-id", // required
    },
    // This endpoint requires session cookies.
    headers: await headers(),
});

const data = await auth.api.getApiKey({    query: {        configId,        id: "some-api-key-id", // required    },    // This endpoint requires session cookies.    headers: await headers(),});

Parameters

configIdstring

用于 API 密钥查找的配置 ID。如果未提供，则使用默认配置。

idstringrequired

API 密钥的 ID。

返回结果

返回除 key 字段外的所有 API 密钥详细信息。如果失败，则抛出 APIError。

type Result = Omit<ApiKey, "key">;

更新 API 密钥

POST/api-key/update

const { data, error } = await authClient.apiKey.update({
    configId,
    keyId: "some-api-key-id", // required
    name: "some-api-key-name",
});

const { data, error } = await authClient.apiKey.update({    configId,    keyId: "some-api-key-id", // required    name: "some-api-key-name",});

Parameters

configIdstring

用于 API 密钥查找的配置 ID。如果未提供，则使用默认配置。

keyIdstringrequired

要更新的 API 密钥的 ID。

namestring

密钥的名称。

POST/api-key/update

const data = await auth.api.updateApiKey({
    body: {
        configId,
        keyId: "some-api-key-id", // required
        userId: "some-user-id", // server-only
        name: "some-api-key-name",
        enabled: true, // server-only
        remaining: 100, // server-only
        refillAmount: 100, // server-only
        refillInterval: 1000, // server-only
        metadata: { "key": "value" }, // server-only
        expiresIn: 60 * 60 * 24 * 7, // server-only
        rateLimitEnabled: true, // server-only
        rateLimitTimeWindow: 1000, // server-only
        rateLimitMax: 100, // server-only
        permissions, // server-only
    },
});

const data = await auth.api.updateApiKey({    body: {        configId,        keyId: "some-api-key-id", // required        userId: "some-user-id", // server-only        name: "some-api-key-name",        enabled: true, // server-only        remaining: 100, // server-only        refillAmount: 100, // server-only        refillInterval: 1000, // server-only        metadata: { "key": "value" }, // server-only        expiresIn: 60 * 60 * 24 * 7, // server-only        rateLimitEnabled: true, // server-only        rateLimitTimeWindow: 1000, // server-only        rateLimitMax: 100, // server-only        permissions, // server-only    },});

Parameters

configIdstring

用于 API 密钥查找的配置 ID。如果未提供，则使用默认配置。

keyIdstringrequired

要更新的 API 密钥的 ID。

userIdstringserver

拥有该 API 密钥的用户 ID。server-only。

namestring

密钥的名称。

enabledbooleanserver

API 密钥是否启用。server-only。

remainingnumberserver

剩余的请求数量。server-only。

refillAmountnumberserver

补充数量。server-only。

refillIntervalnumberserver

补充间隔（以毫秒为单位）。server-only。

metadataany | nullserver

API 密钥的元数据。server-only。

expiresInnumberserver

API 密钥的过期时间（以秒为单位）。server-only。

rateLimitEnabledbooleanserver

是否启用速率限制。server-only。

rateLimitTimeWindownumberserver

每个请求计数的时间窗口（以毫秒为单位）。server-only。

rateLimitMaxnumberserver

在一个窗口内允许的最大请求数。一旦达到 maxRequests，请求将被拒绝，直到 timeWindow 过去，之后 timeWindow 将重置。server-only。

permissionsRecord<string, string[]>server

更新 API 密钥的权限。server-only。

返回结果

如果失败，则抛出 APIError。成功时返回 API 密钥详细信息，但不包含 key 字段。

删除 API 密钥

POST/api-key/delete

Notes

此端点从用户角度尝试删除 API 密钥。它会检查用户 ID 是否与密钥所有者匹配，以确定是否可以删除它。如果您希望在不进行这些检查的情况下删除密钥，我们建议您使用 ORM 直接修改数据库。

const { data, error } = await authClient.apiKey.delete({
    configId,
    keyId: "some-api-key-id", // required
});

const { data, error } = await authClient.apiKey.delete({    configId,    keyId: "some-api-key-id", // required});

Parameters

configIdstring

用于 API 密钥查找的配置 ID。如果未提供，则使用默认配置。

keyIdstringrequired

要删除的 API 密钥的 ID。

POST/api-key/delete

Notes

const data = await auth.api.deleteApiKey({
    body: {
        configId,
        keyId: "some-api-key-id", // required
    },
    // This endpoint requires session cookies.
    headers: await headers(),
});

const data = await auth.api.deleteApiKey({    body: {        configId,        keyId: "some-api-key-id", // required    },    // This endpoint requires session cookies.    headers: await headers(),});

Parameters

configIdstring

用于 API 密钥查找的配置 ID。如果未提供，则使用默认配置。

keyIdstringrequired

要删除的 API 密钥的 ID。

返回结果

如果失败，则抛出 APIError。成功时返回：

type Result = {
  success: boolean;
};

列出 API 密钥

GET/api-key/list

const { data, error } = await authClient.apiKey.list({
    query: {
        configId,
        organizationId,
        limit,
        offset,
        sortBy,
        sortDirection,
    },
});

const { data, error } = await authClient.apiKey.list({    query: {        configId,        organizationId,        limit,        offset,        sortBy,        sortDirection,    },});

Parameters

configIdstring

根据配置 ID 进行筛选。如果未提供，则返回所有配置的密钥。

organizationIdstring

要列出密钥的组织 ID。如果提供，则返回组织拥有的密钥。如果未提供，则返回当前会话用户拥有的密钥。

limitnumber

返回的 API 密钥数量。

offsetnumber

分页开始位置（偏移量）。

sortBystring

排序字段（例如："createdAt"、"name"、"expiresAt"）。

sortDirection"asc" | "desc"

排序方向。

GET/api-key/list

const data = await auth.api.listApiKeys({
    query: {
        configId,
        organizationId,
        limit,
        offset,
        sortBy,
        sortDirection,
    },
    // This endpoint requires session cookies.
    headers: await headers(),
});

const data = await auth.api.listApiKeys({    query: {        configId,        organizationId,        limit,        offset,        sortBy,        sortDirection,    },    // This endpoint requires session cookies.    headers: await headers(),});

Parameters

configIdstring

根据配置 ID 进行筛选。如果未提供，则返回所有配置的密钥。

organizationIdstring

要列出密钥的组织 ID。如果提供，则返回组织拥有的密钥。如果未提供，则返回当前会话用户拥有的密钥。

limitnumber

返回的 API 密钥数量。

offsetnumber

分页开始位置（偏移量）。

sortBystring

排序字段（例如："createdAt"、"name"、"expiresAt"）。

sortDirection"asc" | "desc"

排序方向。

返回结果

如果失败，抛出 APIError。成功时返回分页响应：

type Result = {
  apiKeys: Omit<ApiKey, "key">[];
  total: number;
  limit?: number;
  offset?: number;
};

分页用例

// 获取当前用户的前 10 个 API 密钥
const result = await authClient.apiKey.list({
  query: { limit: 10 }
});

// 获取第二页（每页10条）
const page2 = await authClient.apiKey.list({
  query: { limit: 10, offset: 10 }
});

// 按创建时间排序（最新优先）
const sorted = await authClient.apiKey.list({
  query: { sortBy: "createdAt", sortDirection: "desc" }
});

// 分页和排序结合
const combined = await authClient.apiKey.list({
  query: { 
    limit: 20, 
    offset: 0, 
    sortBy: "name", 
    sortDirection: "asc" 
  }
});

// 列出组织拥有的密钥
const orgKeys = await authClient.apiKey.list({
  query: { organizationId: "org_123" }
});

// 列出指定配置的组织密钥
const orgPublicKeys = await authClient.apiKey.list({
  query: { 
    organizationId: "org_123",
    configId: "public" 
  }
});

删除所有过期的 API 密钥

此功能会删除所有已过期的 API 密钥。

const data = await auth.api.deleteAllExpiredApiKeys();

const data = await auth.api.deleteAllExpiredApiKeys();

我们会在每次调用任何 apiKey 插件的接口时自动删除过期密钥，但调用频率限制为每 10 秒冷却一次，以防多次访问数据库。

功能

安装

安装插件

将插件添加到服务器

迁移数据库

添加客户端插件

使用方法

创建 API 密钥

返回结果

验证 API 密钥

结果

获取 API 密钥

返回结果

更新 API 密钥

返回结果

删除 API 密钥

返回结果

列出 API 密钥

返回结果

分页用例

删除所有过期的 API 密钥

后续步骤

高级特性

参考

On this page