API密钥

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

API密钥在哪里管理?

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

页面显示两个部分：

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

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

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

2. 填写 密钥信息:

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

3. 选择密钥范围：

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

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

   这将添加全局 org.create 权限。该密钥还需要一个组织范围 org_admin 或 org_super_admin Cloudflare、Capacitor、GitHub、Capgo、code、API、SDK、CLI、npm、bun 在 Capacitor 中，选择 管理员 org_admin binding. When this key creates a new organization, Capgo automatically assigns the key as Super Admin on that new organization.

5. 绑定。 当此密钥创建一个新组织时，__CAPGO_KEEP_0__ 将自动将密钥赋予该新组织的超级管理员。

   • 为应用授予访问权限： 当 限制此密钥仅限于选择的应用 启用时，请在 组织中选择要过滤应用的组织
   • 点击 ”+ Add App”选择一个或多个应用，然后为每个应用 Assign 角色：
     • 应用阅读者 — 只读访问应用。
     • 应用上传者 — 可以上传新包。
     • 应用开发者 — 可以上传包、管理设备、触发原生构建和更新频道设置。
     • 应用管理员 — 对应用有完全访问权。
     • 应用预览 — 预览 CI/CD 生命周期：上传一个捆绑包并创建一个预览频道。该频道仅在此密钥有效期内获得自动、频道范围的生命周期权限。

6. 点击 “创建”.

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

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

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

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

仅选用应用模式下会省略组织角色;它不 会 移除组织关联。每个 app_preview 绑定

仍然	scoped 到其选用的应用和该应用的拥有组织。
app_preview Grant	app.read, app.read_bundles, app.upload_bundlePermissions and boundary 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因此无法删除任意的捆绑包。

注意

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

参见 访问控制参考 为了获得完整的边界。

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

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

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

点击 “Save Changes” 完成后。

如何重新生成API密钥?

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

将会出现一个确认弹窗。确认后:

• 对于 安全（散列）密钥: 在一个模态窗口中显示一次新生成的明文密钥，请立即复制它。
• 对于 明文密钥: 密钥值在服务器端重新生成。

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

如何删除一个 API 密钥?

点击 垃圾箱图标 (列表中的任何键)删除确认对话框

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

遗留密钥

如果您看到密钥在 遗留密钥 部分（没有角色分配的密钥），这些使用较旧的基于模式的权限系统（read, upload, write, all）。它们仍然有效，但不受 RBAC 精细权限的益处。

遗留密钥可以从列表中重新生成和删除，但无法编辑以添加 RBAC 角色。我们建议创建新 RBAC 密钥并删除遗留密钥时可能。

如果您需要直接管理遗留密钥，可以在 控制台.capgo.app/dashboard/apikeys本页面已过时，将在未来更新中删除。

继续使用API Keys

如果您正在使用 API Keys 来规划控制台和API 操作，连接它到 API Overview 查看API Overview 了解__CAPGO_KEEP_0__ Keys 了解 API Keys 为 API Keys 的实现细节 设备 为设备的实现细节， 包 为包的实现细节。