提供的能力
@nocobase/app-plugin-api-keys 为脚本和外部系统提供 API 密钥认证。请求使用 x-api-key，以密钥所属用户的身份执行；带范围的密钥还会受到自身范围限制。
插件提供密钥认证与管理接口，个人管理页和业务接口的范围接入由应用实现。
使用场景与示例
示例：给报表脚本只读访问
- 由应用声明报表业务对应的密钥权限组和记录范围。
- 用户登录密钥管理页，选择已被授予的只读能力和有效期，保存创建时返回的 secret。
- 脚本通过
x-api-key调用报表接口。 - 验证允许的查询成功，写入、超范围记录和撤销后的请求被拒绝。
带范围密钥的有效权限是“用户当前权限与密钥范围的交集”。范围不会授予用户原本没有的权限。使用 auth.required() 的业务接口需要明确允许 scoped keys，并通过授权系统或相应范围检查执行操作；未接入的接口拒绝这类密钥。
开发提示词（交给当前应用目录中的 Coding Agent）：
请使用 API 密钥插件，为报表脚本提供有有效期的只读密钥。
沿用认证配置，为报表声明操作与记录范围，接入个人密钥的创建、轮换和撤销。
只在签发或轮换时展示返回的 secret，不把密钥写入源码或日志。
验证允许查询、越界读取、写入、旧密钥与撤销后的请求。完成标志：脚本只能读取允许的报表记录，写入与失效密钥请求被拒绝。
重要原理与实现
以下是实现本例时的接入位置与预期界面变化；它们是开发说明，具体文件名沿用当前应用结构。
| 接入位置 | 代码或配置变化 | 界面与行为变化 |
|---|---|---|
| 认证配置与插件数组 | 组合 apiKey()、apiKeyClient() 并应用迁移 | 密钥认证与管理端点可用 |
| 个人设置页面 | 接入密钥范围、有效期、轮换与撤销 | 用户管理自己的密钥，secret 只在返回时展示 |
| 报表接口 | 显式支持 scoped keys 并应用数据策略 | 脚本只能访问用户权限与密钥范围的交集 |
接入与配置
除 Client、Server 插件注册和数据库迁移外，还要在服务端认证配置中加入 /server 导出的 apiKey()，在客户端认证配置中加入 /client 导出的 apiKeyClient()。默认模板已组合这些配置，先检查再补充。
只注册服务端插件会创建密钥表，但不会启用 Better Auth 密钥端点；只加 apiKey() 而不执行插件迁移则缺少数据表。插件不注册密钥管理页，应用可使用认证客户端或 /api/apiKeys 构建个人管理页。
创建与使用
用户必须通过交互登录后的会话管理自己的密钥。密钥本身不能创建、修改或删除其他密钥。带范围的密钥可通过以下接口管理：
| 接口 | 用途 |
|---|---|
GET /api/apiKeys/scopeOptions | 获取可选权限组、预设和有效期信息 |
POST /api/apiKeys | 创建密钥，返回一次性的明文 secret |
GET /api/apiKeys | 查看自己的密钥及范围，不返回 secret |
POST /api/apiKeys/:keyId/rotate | 轮换 secret，旧值立即失效 |
DELETE /api/apiKeys/:keyId | 撤销密钥 |
例如，应用挂载在 /main 时，可使用密钥读取其 API 文档：
curl -H 'x-api-key: <your-key>' https://app.example.com/main/api/swagger将 <your-key> 替换为实际密钥，并按应用部署位置调整地址。读取 API 文档成功不代表已获准调用其中每个接口。
AI 开发的约束与验证
本插件的开发约束
- 管理密钥使用登录会话，不能让 API 密钥再管理其他密钥。
- 无范围密钥不等于只读；报表接口必须落实操作和记录范围，而不是只校验 key 有效。
- 测试轮换立即使旧 secret 失效，以及用户失去权限、过期和撤销后的调用。
使用边界
无范围密钥继承所属用户的权限，不能把它描述成默认只读。用户失去权限或被停用后，密钥也受到影响。apiKeys.maxScopedKeyDays 可限制带范围密钥的有效期；轮换后需要更新调用方保存的 secret。
上述检查是接入后的验收要求，不表示本文已完成运行验证。让 Agent 报告实际改动、执行过的检查和未验证项；项目指引、Skills 与通用检查流程见持续开发应用和测试。
源码依据：插件公开入口与实现。