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() 
    ]
})

迁移数据库

运行迁移或生成模式(schema)以向数据库添加必要的字段和表。

npx auth migrate

npx auth generate

详细信息见模式(Schema)部分，可手动添加字段。

添加客户端插件

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，仅服务器使用。不使用会话头时，用户拥有的密钥必须设置此项。

organizationIdstring

API 密钥所属组织 ID。针对组织拥有的密钥（配置中设置 references: "organization"）必填。

prefixstring

API 密钥的前缀。

remainingnumberserver

剩余请求次数，仅服务器使用。

metadataany | null

API 密钥的元数据。

refillAmountnumberserver

剩余请求次数的补充数量，仅服务器使用。

refillIntervalnumberserver

补充请求次数的间隔时间（毫秒），仅服务器使用。

rateLimitTimeWindownumberserver

计数请求的时间窗口（毫秒）。达到最大请求数后，请求将被拒绝，直到时间窗口结束并重置，服务器端使用。

rateLimitMaxnumberserver

时间窗口内允许的最大请求数。达到后请求被拒，等待时间窗口重置，服务器端使用。

rateLimitEnabledbooleanserver

是否启用速率限制，仅服务器使用。

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，仅服务器使用。

namestring

密钥名称。

enabledbooleanserver

是否启用 API 密钥，仅服务器使用。

remainingnumberserver

剩余请求次数，仅服务器使用。

refillAmountnumberserver

补充数量，仅服务器使用。

refillIntervalnumberserver

补充时间间隔（毫秒），仅服务器使用。

metadataany | nullserver

API 密钥元数据，仅服务器使用。

expiresInnumberserver

过期时间（秒），仅服务器使用。

rateLimitEnabledbooleanserver

是否启用速率限制，仅服务器使用。

rateLimitTimeWindownumberserver

计数请求的时间窗口（毫秒），仅服务器使用。

rateLimitMaxnumberserver

时间窗口内允许的最大请求数，服务器端使用。

permissionsRecord<string, string[]>server

更新 API 密钥的权限，仅服务器使用。

返回结果

如果失败，则抛出 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

此接口尝试从用户视角删除 API 密钥。会验证用户 ID 是否与密钥所有者匹配才能删除。如需跳过这些校验，建议直接使用 ORM 操作数据库。

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 密钥

返回结果

分页用例

删除所有过期的 API 密钥

后续步骤

高级功能

参考

本页目录