Orbit API 令牌和 REST API

API 令牌允许脚本、CI 管道或您自己的工具在没有浏览器会话的情况下驱动 Orbit：触发部署、报告 CI 检查结果、下载构建工件、管理 cron 作业等，所有操作都通过您自己设定范围的 Bearer 令牌进行身份验证。

令牌位置

打开 Orbit，从顶级导航中选择 Tokens。该页面标题为 API Access Tokens，并在前面说明了其规则：令牌仅在创建时显示一次。

完整的端点文档只需点击一下即可查看。API Reference 卡片有一个 View docs 按钮，可打开 Orbit 每个端点的面板内参考文档。

创建令牌

1. 点击 New token。
2. 给它取一个 Token name。按照将使用它的对象命名，例如 CI 工作流，这样日后清单更易读。
3. 选择其 Scopes。
4. 可选：设置一个 Expiry。留空表示令牌永不过期。
5. 点击 Create token。

原始令牌在 One-time reveal 标题下显示一次，带有复制按钮。直接将其粘贴到您的 CI 密密钥存储中。无法再次查看它：只有令牌的 SHA-256 哈希被存储，因此即使是 KapsuleHost 也无法为您恢复它。

一个账户最多可以拥有 20 个活跃令牌。创建第 21 个令牌会被拒绝，并显示消息要求您先撤销现有的令牌。

范围

范围是令牌的核心：每个令牌只具有您授予它的权限。

新令牌默认为 deploy:write 和 project:read，这正是部署管道需要的，仅此而已。

授予完成工作所需的最小权限集。仅需报告 CI 结果的令牌不需要 project:write。只读监控脚本既不需要写入范围。参考文档中的每个端点都列出了它所需的最小范围。

使用令牌

身份验证是针对 API 基础 https://kapsulehost.com 的 Bearer 头：

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

令牌页面提供了现成的 CI/CD usage 代码片段和 GitHub Actions starter 工作流。该启动器保存为 .github/workflows/orbit-deploy.yml 并需要两个仓库密钥，ORBIT_TOKEN 和 ORBIT_PROJECT_ID。从页面复制两者，而不是手动转录。

API 覆盖范围

面板内参考文档通过其参数和所需范围记录了每个领域：

• Deployments：触发部署，可选地在指定分支上进行，可选地安排在未来五分钟至三十天之间的时间，附带最多 500 个字符的备注。列表支持在提交、消息、分支和作者中进行模糊搜索，加上对分支、状态和环境的过滤，游标分页每页最多 100 个结果。
• Deployment checks：在 CI 作业开始时注册质量门，然后在完成时报告结果。失败的 required 检查会将部署移至 FAILED 并将环境恢复为上一次成功的部署，这是使您自己的测试套件成为真正部署门的方式。
• Branch protection：全局模式规则，阻止自动部署，直到所需检查通过，可选地需要某人批准。每个项目最多十条规则。
• Build artifacts：获取成功部署的已编译输出的预签名下载 URL。URL 有效期为十五分钟。
• Project transfer：启动、取消和检查向另一个账户转移的状态。请参阅转移 Orbit 项目。
• Cron jobs：列出、创建、更新、删除、触发和读取执行历史。请参阅 Orbit Cron Jobs。
• Timeline annotations：创建和管理事件、发布、里程碑、备注和标志注释。请参阅 Orbit Timeline Annotations。
• Status page：读取和写入公共状态页面配置。请参阅 Orbit Status Page。
• Edge functions：列出、创建、更新和部署边缘处理程序。请参阅 Orbit Edge Functions。

来自面板的会话身份验证与 Bearer 令牌并行工作，因此您可以从浏览器调用的端点通常也可以从脚本调用。

Turbo 远程缓存

令牌页面还提供了 Remote Build Cache 卡片。它实现了 Turborepo 远程缓存协议，让单体仓库在 CI 运行和开发机器之间共享构建缓存。

在卡片上启用它，复制其生成的令牌，并将其与您的账户 ID 一起设置为 CI 环境中的 TURBO_TEAM。接受每个最多 150 MB 的工件。该卡片还提供 Rotate token 和 Disable。

如果您的单体仓库 CI 大部分时间都在重新构建未更改的包，这是页面上最高价值的功能。

管理清单

Token inventory 列出每个活跃令牌的以下内容：

• 何时 Created。
• 何时 Last used，或 Never。
• 何时 Expires，过期后带有 expired 徽章。

Last used 列是需要审计的。从未使用过的令牌要么配置错误，要么被遗忘，无论哪种情况，它都是一个闲置的凭据。该页面自己的提示直言不讳地说出来：撤销任何您不认识的令牌。

撤销令牌

点击行上的撤销控制。确认明确表述：使用该令牌进行身份验证的所有内容会立即失去访问权限，并且这无法撤销。

当管道停用、有权访问 CI 密钥的人员离职或您怀疑令牌泄露时，撤销令牌。没有部分撤销，也没有宽限期，这正是您在泄露情况下所需的。

故障排除

401 Unauthorized。头部不正确或令牌已被撤销或过期。检查头部是否为 Authorization: Bearer <token> 加一个单空格，以及您的 CI 密钥是否没有尾随换行符。

403 Forbidden。令牌有效但缺少该端点的范围。参考文档列出了每个端点的最小范围。范围在创建时固定，因此请创建一个具有正确权限集的新令牌。

creation 时出现 429。您已达到二十令牌限制。从清单中撤销某些内容。

工件 URL 停止工作。预签名 URL 有效期为十五分钟。请求一个新的而不是存储 URL。

计划的部署被拒绝。计划的时间必须在未来的五分钟至三十天之间。

接下来的步骤

• 部署您的项目了解触发的部署实际执行的操作。
• Orbit 部署管道查看您的 API 部署将满足哪些门。
• Orbit 计划限制了解您的计划包含什么。