API密钥

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

API密钥在哪里管理?

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

页面显示两个部分:

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

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

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

2. 填写 密钥信息:

   • 名称 (必填) — 密钥的描述性标签（例如，“CI/CD 部署”或“监控只读”）。
   • 创建安全密钥 (选项) — 当选中时，密钥在服务器端进行哈希处理。原始密钥仅在创建后显示一次，之后无法再次获取。 仅显示一次 创建后无法再次获取。
   • 设置过期日期 (选项) — 选择一个日期后，密钥将失效。某些组织通过政策强制实施密钥过期。

3. 选择密钥范围：

   • 组织级别访问 — 选择一个 组织角色 来定义组织内的基本权限。可用的角色取决于您的角色级别：
     • None — 无组织级别访问权
     • Member — 基本读取组织的访问权
     • Admin — 对组织和所有应用程序有完全的管理访问权
   • App-only access — 启用 仅限于选择的应用。每个应用程序绑定仍然与该应用程序的拥有组织相关联;此模式仅排除了组织级别的RBAC角色

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

   This adds the global org.create permission. The key also needs an organization-scoped org_admin 或 org_super_admin This adds the global 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.

5. permission. The key also needs an organization-scoped

   • 或 This adds the global permission. The key also needs an organization-scoped 或是组织范围内的 以显示其应用。已选择的应用绑定仍与其拥有组织相关联；此过滤器不会授予组织级访问权限。
   • 点击 ”+ Add App”添加应用
     • 点击 选择一个或多个应用，然后为每个应用 assignments 角色:
     • 应用阅读者 —仅读取应用的权限。
     • 应用上传者 —可以上传新包。
     • 应用开发者 —可以上传包、管理设备、触发本机构建和更新频道设置。
     • App 预览 — 预览 CI/CD 生命周期：上传一个包并创建一个预览频道。该频道仅在此密钥有效期内自动获得频道范围的生命周期权限。

6. 点击 “创建”.

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

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

使用 应用预览 用于 CI 的应用预览

1. 创建一个临时、非公开的预览频道，上传并推广一个包，然后删除频道和包。它没有对现有的默认频道或主频道的生命周期访问。 创建 RBAC 密钥并启用.
2. 限制此密钥到选定的应用 在组织中过滤应用
3. ,选择组织以显示其应用；每个选定的应用仍然与其拥有组织相关联。
4. 仅添加用于预览部署的应用或应用。 选择 应用预览
5. 创建一个安全的密钥，设置一个适当的过期日期，并将其存储在您的CI密钥管理器中。

此选项仅适用于特定应用，省略了组织级别的角色；它 不 删除组织关联。每个 app_preview 绑定

仍然	scoped 到其所选应用程序和该应用程序的拥有组织。
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 也记录了哪个 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 创建频道、上传捆绑包并在一个流程中推广它。最后一个命令使用一个狭窄的原子清理路线：它只有在密钥拥有预览频道和其链接的、未共享的捆绑包时才会成功。 应用预览 仍然没有通用 bundle.delete，因此无法删除任意的捆绑包。

注意

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

查看 访问控制参考 查看完整边界。

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

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

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

点击 “Save Changes” 完成后

如何重新生成API密钥?

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

确认弹出对话框后：

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

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

如何删除一个 API 密钥？

点击任何列表中的 垃圾桶图标 (删除)

确认删除对话框

__CAPGO_KEEP_0__ 密钥删除确认对话框

标题：遗留密钥 如果您看到列表中的 遗留密钥read, upload, write, all(没有角色 assignments 的密钥)，这些使用较旧的基于模式的权限系统（

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

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

继续使用API密钥

如果您正在使用 API密钥 来规划控制台和API操作，请将其与 API概览 连接，了解API概览中的实现细节 介绍 了解介绍中的实现细节 API 键 用于API 键的实现细节 设备 用于设备的实现细节，并且 包 用于包的实现细节。