API 密钥

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

API 用于对 Capgo API 的请求进行身份验证。这些 Key 属于特定组织，并可分配 RBAC 角色以实现细粒度的访问控制。每个 Key 还可以设置可选的过期日期，并支持创建“安全”（哈希）Key，其明文值仅在创建时显示一次。

使用 API 密钥

请使用该端点文档中指定的身份验证请求头。对于使用 API 密钥的请求， authorization 是有效的：

curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

部分端点也支持专用的密钥请求头。你可以使用频道 API 来接收 authorization 或 capgkey；在进行 preview-channel 自动化时，请使用其中一个请求头。

RBAC 权限

API 密钥使用与用户账号相同的基于角色的访问控制 (RBAC) 系统。通过 Web 应用或 API 创建或管理密钥时，您需要在两个层级分配角色：

组织角色 — 定义该密钥在整个组织范围内的基础权限（例如， org_admin 或 org_member).
App 角色 — 特定 App 的权限（例如， app_admin, app_developer, app_uploader, app_reader，或 app_preview).

如果 API 密钥拥有显式的角色绑定， 则仅针对这些绑定 进行权限检查。密钥不会继承密钥所有者的个人权限。

预览 Channel 自动化

绑定 app_preview 仅绑定到用于 CI 的预览 App：该流程会创建一个临时的非公开预览频道，上传并提升 bundle，然后删除这两者。

{
  "name": "PR preview key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "app_preview",
      "scope_type": "app",
      "org_id": "<OWNING_ORG_UUID>",
      "app_id": "<APP_UUID>"
    }
  ]
}

org_id 是该 App 所属组织的 UUID。 app_id 是 App 记录的内部 UUID，而非 CLI 命令所使用的公开 App 标识符（例如， com.example.app）。即使该 Key 没有组织级角色，该绑定仍限定在组织内。

App 级 app_preview 角色仅包含 app.read, app.read_bundles, app.upload_bundle，以及 app.create_channel。当该 Key 创建频道时，Capgo 会自动在新建的频道上添加一个 channel_preview 绑定。该子绑定将授予 channel.read, channel.promote_bundle，以及 channel.delete 仅限于该密钥创建的 channel。

app_preview 保留 app.read，因此这并非严格的 channel 读取隔离：该密钥可能会枚举所选 App 中的 channel 元数据。自动子绑定限制了 生命周期变更 至该密钥创建的 channel。

Capgo 会记录上传每个 bundle 的 App Preview 密钥。该密钥仅能将其自身创建的 bundle 提升至对应的 preview channel。它无法访问现有默认/主 channel、由其他 preview 密钥创建的 channel 或其他密钥的 bundle 的 channel lifecycle。在此工作流中，请省略 public 并且切勿使用 --default.

使用 channel delete <preview-channel> <public-app-id> --delete-bundle 进行清理。这是一个具有所有权检查的原子化 preview 清理路由；它仅会移除调用密钥所属的 preview channel 及关联的 bundle。 app_preview 不授予通用的 bundle.delete.

有关 dashboard 设置及完整的 CLI 示例，请参阅在预览工作流中使用 App Preview 密钥.

创建组织权限

现在使用 API 密钥创建组织时，将使用显式的全局权限： org.create.

此权限与常规的组织/应用角色绑定是分离的，因为在调用 POST /organization/ 时，新的组织尚未创建。要使用 API 密钥创建组织：

API 密钥必须包含 org.create 中的 global_permissions.
同一个 API 密钥还必须具备当前组织范围内的 org_admin 或 org_super_admin 绑定。
新的 API 密钥默认不会获得 org.create 该权限。请启用 “允许创建组织” （在 dashboard 中创建或编辑 RBAC API 密钥时）。
现有的具备写权限的 org admin/super admin API 密钥已回填该权限， org.create 因此现有集成可以继续创建组织。

当 API 密钥创建组织时，Capgo 会自动将同一个 API 密钥分配为 org_super_admin 新创建组织上的角色。这样，集成无需额外手动绑定角色，即可管理它刚刚创建的组织。

如果您通过 API 创建了 API 密钥，请包含 global_permissions 以及组织管理员绑定：

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create 仅适用于创建组织。删除组织仍需目标组织的删除权限，通常通过 org_super_admin.

安全 (Hashed) 密钥

创建安全密钥时，服务器会生成密钥内容并仅返回一次明文。系统仅存储哈希值。这意味着：

明文密钥 无法被检索 在创建之后。
重新生成会产生一个新的明文密钥（仅显示一次）并更新存储的哈希值。
生产环境建议使用 Hashed 密钥。

某些组织通过以下方式强制执行哈希密钥： enforce_hashed_api_keys 组织策略。

过期时间

密钥可以设置可选的过期日期。过期的密钥将在权限检查层被拒绝。

组织策略可以强制执行：

强制过期 (require_apikey_expiration) — 所有新密钥都必须设置有效期。
最大 TTL (max_apikey_expiration_days) — 有效期不能超过当前时间 N 天以后。

安全最佳实践

最小权限原则: 分配能保证集成正常运行的最严格角色
定期轮换: 使用 regenerate 功能定期轮换 API keys
安全存储: 安全存储 API keys，切勿将其提交至版本控制系统
使用哈希密钥: 为生产环境集成创建安全的 (hashed) keys
设置有效期: 为用于临时访问或 CI/CD 的 keys 务必设置过期日期
作用域限制: 将 keys 限制在特定 App 内，并赋予最小必要的角色

常见用例

CI/CD 集成: Create keys scoped to specific apps with the app_uploader 或 app_developer 并设置过期日期。
PR Preview Channels：使用 app_preview 仅在 CI 需要上传 bundle 时，在预览版 App 上启用，从而自动创建临时 channel 并原子化地清理其对应的 channel 和 bundle。
部署自动化: 在自动化部署脚本中使用具有 app_developer 角色的密钥。
监控工具: 使用 app_reader 角色创建用于外部监控集成的密钥。
管理员权限: 谨慎使用具有 org_admin 角色的密钥进行管理工具操作。
第三方集成: 使用最小权限角色创建仅限特定 App 使用的密钥。
组织配置: 使用 org_admin 或 org_super_admin RBAC 密钥配合 org.create 仅限需要创建组织的受信任自动化任务使用。

继续阅读 API 密钥

如果你正在使用 API 密钥 用来规划身份验证和账户流程，并将它与 @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 有关 @capgo/capacitor-native-biometric 的实现细节，双因素认证有关双因素认证的实现细节，以及 SSO (企业版) 有关 SSO (Enterprise) 的实现细节。