KapsuleHost 为您提供两个开发者界面：限定范围的 API 密钥用于以编程方式读取您的账户，以及远程构建缓存用于加速您自己的机器和 CI 运行器上的 Turborepo 和 Nx 构建。
默认情况下，两者都未启用。两者都从设置创建，两者都会向您交付一个密钥，且仅交付一次。
创建 API 密钥
API 密钥位于设置下，然后是安全，在 API 密钥卡中。
- 转到设置，然后安全。
- 滚动到 API 密钥并点击新密钥。
- 为密钥指定一个名称。该字段建议"密钥名称（例如 My automation script）"。该名称仅供您使用，因此请让它说明密钥将在何处使用。
- 点击范围芯片以选择密钥可以执行的操作。三个读取范围已预先选定：
read:sites、read:email和read:domains。点击芯片以添加或删除它。 - 点击创建。
完整密钥出现一次，在一个绿色面板中，标题为"立即复制"。将其直接复制到您的密钥存储中。当您关闭该面板时，密钥消失：仅保留一个短前缀，这是列表以后能显示的全部。
密钥永远不会显示第二次，并且无法恢复。如果您丢失了它，撤销该密钥并创建一个新的。不要将其粘贴到共享文档、工单、提交或聊天消息中。
只有所有者和管理员角色可以创建密钥。任何其他角色都会收到权限错误。创建密钥时，安全警报电子邮件会发送到创建该密钥的人的地址，因此意外收到其中之一是值得立即调查的。
范围
提供七个范围：
| 范围 | 授予 |
|---|---|
read:sites | 读取您的网站 |
write:sites | 保留用于网站上的写入操作 |
read:email | 读取您的邮箱 |
write:email | 保留用于邮箱上的写入操作 |
read:domains | 读取您的域 |
write:domains | 保留用于域上的写入操作 |
read:billing | 保留用于读取计费数据 |
客户 API 目前是只读的。write: 范围和 read:billing 可以在密钥上选择，但目前没有客户端点使用它们，因此授予它们不会改变任何内容。仅授予您实际需要的读取范围，并在写入端点发货时重新访问密钥。
使用密钥
在 Authorization 标头上将密钥作为承载者令牌发送。
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
三个端点接受客户 API 密钥：
| 端点 | 所需范围 | 返回 |
|---|---|---|
GET /api/v1/sites | read:sites | 您的网站，包括域、应用程序类型和状态 |
GET /api/v1/domains | read:domains | 您的域，包括状态和到期日期 |
GET /api/v1/mailboxes | read:email | 您的邮箱 |
没有密钥、未知密钥或已撤销密钥的请求返回 401。具有正确范围的有效密钥返回 403，并带有一条消息，命名所需的范围。每次成功调用都会更新密钥的上次使用时间戳。
轻轻轮询。这些端点读取实时账户数据，针对它们的紧密循环与滥用无法区分。对于仪表板需要的任何内容，每分钟一次都很充分；每小时一次通常足够了。
审查和撤销密钥
API 密钥表按名称、前缀（密钥的可见开头）和范围列出每个活跃密钥。点击行末尾的撤销以将其禁用。
撤销立即生效，没有确认对话框。使用该密钥的下一个请求失败，返回 401。已撤销的密钥无法恢复，因此在点击之前请确保您知道什么在使用它。
密钥属于账户，而不是创建它们的人。从团队页面移除团队成员不会撤销他们创建的密钥。将密钥审查纳入您的员工离职流程：移除该人，然后来这里撤销他们创建的任何东西。
密钥创建和撤销都记录在审计日志中，在 api_key.* 操作下，包含执行者和来源 IP 地址。
远程构建缓存
设置边栏的高级组中的开发者页面提供远程构建缓存。该面板将其描述为"通过在机器和 CI 管道之间共享分布式缓存来加速 Turborepo 和 Nx 构建"的方式。
- 转到设置，然后开发者。
- 点击启用远程缓存。
- 从标题为"已生成新令牌。立即复制它，它不会再次显示"的面板中复制令牌。
然后在您的 CI 配置或本地 .env.local 中设置两个环境变量：
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
团队 ID 是您的 KapsuleHost 账户 ID，显示在同一页面上的设置说明中。
该页面说明了其自身的兼容性：Turborepo 1.x 及更高版本、Nx 16 及更高版本，以及任何实现相同远程缓存协议的工具。工件按账户存储，永远不会跨账户共享。
卡上还有两个进一步的控件：
- 轮换令牌发出新令牌并使旧令牌失效。任何仍保留旧令牌的 CI 作业都会停止使用缓存，因此请一起轮换和更新您的密钥。
- 禁用完全关闭缓存。
在两者之间选择
它们解决的是无关问题，不可互换。
当 KapsuleHost 外部的某些东西需要了解您账户的状态时，使用 API 密钥：列出您网站的状态板、警告您有关域名即将过期的脚本、库存导出。
当您的构建速度缓慢因为每台机器和每次 CI 运行都重新构建相同的未更改包时，使用远程构建缓存。它与您托管的网站无关，不读取您的账户数据。
故障排除
每个请求都返回 401。确认您在 Authorization: Bearer <key> 上以单个空格发送了标头，密钥在复制时未被截断，并且未被撤销。将密钥的开头与前缀列进行比较，以确保您使用的是您认为的密钥。
请求返回 403 并命名范围。密钥不包含该范围。范围在创建密钥时是固定的，因此创建一个具有正确范围的替代品并撤销旧的。
我看不到 API 密钥卡。它在安全页面上，不在开发者页面上。开发者页面仅保存构建缓存。
新密钥按钮没有反应。您的角色低于管理员。请联系所有者或管理员。
构建未命中缓存。检查 TURBO_TOKEN 和 TURBO_TEAM 是否都存在于构建环境中，令牌自设置以来是否未被轮换，以及页面是否仍显示活跃徽章。