API 密钥

复制一个包含安装步骤和本插件的完整Markdown指南的配置提示。

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

API密钥在哪里管理?

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

页面显示两个部分:

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

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

点击 ”+” 按钮顶部的 RBAC 密钥表。
填写 密钥信息:
- 名称 (必填) — 密钥的描述性标签（例如，“CI/CD 部署”或“监控只读”）。
- 创建安全密钥 (可选) — 当选中时，密钥在服务器端进行散列。原始密钥仅在创建后显示一次，之后无法再次获取。 仅显示一次 设置过期日期
- (可选) — 选择一个日期后，密钥将失效。某些组织通过政策强制实施密钥过期。 __CAPGO_KEEP_0__密钥创建表单（含名称、安全密钥选项和过期日期）

API key creation form with name, secure key option, and expiration

组织级别访问
- — 选择一个 组织角色 以定义组织内的基本权限。可用的角色取决于您的角色等级： key creation form with name, secure key option, and expiration
  - None — 无组织级别访问权
  - Member — 基本读取组织的访问权
  - Admin — 对组织和所有应用程序有完全的管理访问权
- App-only access — 启用 仅限于选择的应用程序每个应用程序绑定仍然与该应用程序的拥有组织相关联;此模式仅排除了组织级别的RBAC角色
如果需要通过公共API创建组织，启用 允许创建组织.

This adds the global org.create permission. The key also needs an organization-scoped org_admin 或 org_super_admin permission. The key also needs an organization-scoped 或 permission. The key also needs an organization-scoped org_admin binding. When this key creates a new organization, Capgo automatically assigns the key as Super Admin on that new organization.
permission. The key also needs an organization-scoped
- 或 permission. The key also needs an organization-scoped permission. The key also needs an organization-scoped permission. The key also needs an organization-scoped 以显示其应用。已选择的应用绑定仍与其拥有组织相关联;此过滤器不会授予组织级访问权限。
- 点击 ”+ Add App”添加应用
  - 选择一个或多个应用，然后为每个应用赋予角色: 应用读者
  - —仅读取应用的权限。 应用上传者
  - —可以上传新包。 应用开发者
  - —可以上传包、管理设备、触发本机构建和更新频道设置。 应用管理员
  - App 预览 — 预览 CI/CD 生命周期：上传一个捆绑包并创建一个预览频道。该频道仅在此密钥有效期内自动获得频道范围的生命周期权限。
点击 “创建”.
如果您勾选了 创建安全密钥,一个模态窗口会显示明文密钥。 立即复制它 — 模态窗口关闭后无法恢复。

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

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

创建 RBAC 密钥并启用 限制此密钥仅用于选定的应用.
在 组织中筛选应用, 选择组织以显示其应用；每个选定的应用仍与其拥有组织相关联。
仅添加用于预览部署的应用。
选择 App Preview 为每个选定的应用
创建一个安全的密钥，设置一个适当的过期日期，并将其存储在您的CI密钥管理器中。

这个选定应用程序模式省略了组织级别的角色；它不删除组织关联。每个 app_preview 绑定

仍然	受其选定的应用程序和该应用程序的拥有组织的约束。
`app_preview` 授予	`app.read`, `app.read_bundles`, `app.upload_bundle`权限 `app.create_channel`.
和 `channel_preview` 边界	When this key creates a channel, Capgo automatically gives the key `channel.read`, `channel.promote_bundle`，和 `channel.delete` 仅限于该频道。

app_preview 保留 app.read因此，密钥可能枚举所选应用程序中的频道元数据。自动子绑定是一个管理边界：它不会为密钥没有创建的频道授予生命周期变更。

Capgo 也记录了哪个 App 预览密钥上传了一个捆绑包。密钥可以在其创建的每个预览频道上设置自己的捆绑包，并可以清除该对。它不会接收到一个现有默认或主频道、由另一个预览密钥创建的频道或另一个密钥的捆绑包的频道绑定。

对于一个典型的 CI 任务，使用一个唯一的频道名称每个拉取请求：

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

为一个新频道 bundle upload --channel 创建频道、上传捆绑包并在一个流程中推广它。最后一个命令使用一个狭窄的原子清理路线：它只有在密钥拥有预览频道及其链接的未共享捆绑包时才会成功。 App 预览 仍然没有一般 bundle.delete, 因此无法删除任意的捆绑包。

参见访问控制参考完整边界的参考。

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

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

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

点击 “Save Changes” 当前角色设置的__CAPGO_KEEP_0__密钥编辑页面

标题：如何重新生成API密钥?

To regenerate the secret value of an API key, click the 当完成时，点击 (Regenerate) 在列表中的任意一个密钥。

确认弹出对话框后：

对于 安全（散列）密钥: 生成并显示一次新密文密钥。立即复制它。
对于 明文密钥: 服务器端重新生成密钥值。

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

如何删除一个 API 密钥？

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

此键立即被撤销 — 使用它的任何请求都会失败。

遗留密钥

如果您看到密钥在 遗留密钥 （没有角色 assignments 的密钥）read, upload, write, all这些使用较旧的基于模式的权限系统（

它们仍然有效，但不受 RBAC 精细权限的益处。

如果您需要直接管理遗留密钥，请仍然可以在 console.capgo.app/dashboard/apikeys中找到它们。该页面已被弃用，将在未来更新中删除。

继续使用API密钥

如果您正在使用 API密钥 来规划仪表板和API操作，请将其连接到 API概览以获取API概览中的实现细节介绍以获取介绍中的实现细节 API 密钥用于API 密钥的实现细节设备用于设备的实现细节,以及包用于包的实现细节。