API Keys

API 键使用基于角色的访问控制（RBAC）。一个键可以具有组织范围的角色、应用范围的绑定或两者。每个应用绑定都与其拥有组织相关联。为了实现最小特权，限制一个键到特定应用而不是赋予组织范围的角色。

哪里管理API密钥?

导航到 设置 > 组织 > API密钥 在 console.capgo.app/settings/organization/api-keys.

页面显示两个部分：

• RBAC密钥 —已分配角色（推荐）的密钥。这些密钥使用新的基于角色的权限系统。
• Legacy密钥 —使用简单模式系统（，）而无角色分配的旧密钥（read, upload, write, all)

如何创建一个新的 API 密钥？

1. 点击 RBAC 密钥表格顶部的 ”+” 按钮。

2. 填写 密钥信息:

   • 名称 (必填) — 密钥的描述性标签（例如，“CI/CD 部署”或“监控只读”）。
   • 创建安全密钥 (可选) — 当勾选时，密钥在服务器端进行散列。明文密钥只显示一次 __CAPGO_KEEP_0__ 在创建后无法恢复。
   • 设置过期日期 (可选) — 选择一个日期后，密钥将失效。一些组织通过政策强制实施过期日期。

3. 选择密钥范围：

   • 组织级访问 — 选择一个 组织角色 来定义组织内的基本权限。可用的角色取决于您的角色级别：
     • 无 — 没有组织级访问。
     • 成员 —— 基本读取组织的访问权限。
     • 管理员 —— 全面对组织及其所有应用程序的管理访问权限。
   • 应用程序仅访问 —— 启用 限制此密钥仅限于选择的应用程序. 每个应用程序绑定仍然与该应用程序的拥有组织相关联；此模式仅省略了组织范围的RBAC角色。

4. 如果密钥需要通过公共 API 创建组织，启用 允许创建组织.

   此添加全局 org.create 权限。密钥也需要组织范围的 org_admin 或 org_super_admin 在仪表盘中，选择 管理员 创建 org_admin 绑定。 当此密钥创建一个新组织时，Capgo会自动将密钥赋予新组织的超级管理员权限。

5. 为应用程序授予访问权限：

   • 当 限制此密钥仅限于选定应用程序 时，选择一个组织在 组织列表中过滤应用程序 来显示其应用程序。 选择的应用程序绑定仍与其所属组织相关联；此过滤器不会授予组织级别的访问权限。
   • 点击 ”+ 添加应用程序”选择一个或多个应用程序，然后为每个应用程序赋予角色：
     • App Reader —— 只读访问应用程序。
     • App Uploader —— 可以上传新包。
     • App Developer —— 可以上传包、管理设备、触发本机构建和更新通道设置。
     • App Admin —— 对应用程序有完全访问权。
     • App Preview —— 预览 CI/CD 生命周期：上传包并创建预览频道。该频道仅在此密钥范围内自动获得频道范围的生命周期权限。

6. Click 创建.

7. 如果您已勾选 创建安全密钥，一个弹出窗口会显示明文密钥。 立即复制它 — 关闭弹出窗口后无法恢复密钥。

使用 App 预览密钥进行预览工作流

使用 App 预览 用于 CI 的临时、非公开预览通道，上传并推广一个包，然后删除通道和包。它没有对现有默认或主通道的生命周期访问权限。

1. 创建 RBAC 密钥并启用 仅限于选择的应用.
2. 下 组织以过滤应用, 选择组织以显示其应用；每个选择的应用都与其拥有组织相关联。
3. 仅添加用于预览部署的应用。
4. 选择 应用预览 为每个选择的应用。
5. 创建一个安全密钥，设置一个适当的过期日期，并将其存储在您的 CI 秘密管理器中。

此仅选择应用的模式省略了组织级角色；它 不 取消组织关联。每个 app_preview 绑定仍然受其选择的应用程序和该应用程序的所有者组织的约束。

授权	权限和边界
app_preview 在选择的应用程序	app.read, app.read_bundles, app.upload_bundle,并且 app.create_channel.
自动 channel_preview 绑定	当此密钥创建一个通道时，Capgo自动为该密钥 channel.read, channel.promote_bundle,并且 channel.delete 仅限于该通道。

app_preview 保留 app.read因此，关键可以枚举所选应用的通道元数据。自动子绑定是界限：它不会为关键没有创建的通道授予生命周期变更。 __CAPGO_KEEP_0__ 还记录了哪个 App 预览关键上传了一个捆绑包。该关键可以在其创建的每个预览通道上设置自己的捆绑包，并清除该对。它不会接收一个已存在的默认或主通道、由另一个预览关键创建的通道或另一个关键的捆绑包的通道绑定。 对于典型的 CI 任务，使用每个拉取请求的唯一通道名称：

Capgo also records which App Preview key uploaded a bundle. The key can set only its own bundle on each preview channel it creates and can clean up that pair together. It does not receive a channel binding for an existing default or main channel, a channel created by another preview key, or another key’s bundle.

复制到剪贴板

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

App 预览 bundle upload --channel 仍然没有一般 ，所以它不能删除任意捆绑包。 App Preview bundle.delete管理

注意

使用一个新的非公开 pr-<number> 频道。不要将 --default, --self-assign,发布选项或 --delete-linked-bundle-on-upload 传递到这个工作流程。一个 应用预览 密钥不能促进、删除或更改一个现有的默认/主要频道、另一个预览密钥的频道或另一个密钥的包。撤销或过期应用绑定也会移除密钥的有效生命周期访问。

参见 访问控制参考 了解有关（编辑）一个__CAPGO_KEEP_0__密钥的方法

如何管理（编辑）一个API密钥?

点击 扳手图标 （管理）列表中的任何RBAC密钥。 这会打开密钥详细页面，您可以：

• 更改密钥 名称.
• 更新 组织角色.
• 启用或禁用 允许创建组织 当密钥具有管理员组织角色时。
• 添加、删除或更改 每个应用程序的角色.

点击 “保存更改” 完成后。

如何重新生成一个 API 键?

要重新生成一个 API 键的密钥值，请点击 刷新图标 (重新生成)列表中的任意一个键

确认弹出框将出现。确认后：

• For secure (hashed) keys：生成并显示一次modal中的新文本密钥，复制它立即。
• For plain keys：服务器端重新生成密钥值。

任何使用旧密钥值的集成将立即停止工作。

如何删除API密钥？

点击 垃圾桶图标 （删除）列表中的任何密钥。确认删除对话框。

立即撤销该密钥 — 使用它的任何请求都会失败。

遗留密钥

如果您看到密钥在 遗留密钥（角色 assignments 无） section（使用旧的模式权限系统（）），这些密钥仍然有效，但不受 RBAC 精细权限的益处。read, upload, write, all遗留密钥可以从列表中重新生成和删除，但无法编辑以添加 RBAC 角色。我们建议创建新 RBAC 密钥并删除遗留密钥时可能。

如果您需要直接管理遗留密钥，可以访问

console.__CAPGO_KEEP_0__.app/dashboard/apikeys console.capgo.app/dashboard/apikeyshttps://github.com/

继续从 API Keys

如果您正在使用 API Keys 来规划仪表板和 API 操作，连接它与 API Overview 了解 API Overview 的实施细节在 介绍 了解介绍的实施细节在 API Keys 了解 API Keys 的实施细节在 设备 对于设备中的实现细节， 捆绑包 对于捆绑包中的实现细节，