API 键

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

API 键用于向 Capgo API 进行身份验证的请求。这些密钥是组织特有的，可以为细粒度访问控制分配 RBAC 角色。每个密钥也可以具有可选的过期日期，并且可以以“安全”（散列）形式创建，仅在第一次显示时显示原始文本值。

使用 API 密钥

使用身份验证头，按照 API 文档所述。对于 API-密钥请求， authorization 被接受：

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

某些端点还接受专用密钥头。 API 通道接受 authorization 或 capgkey; 使用其中一个标题进行预览频道自动化。

RBAC 权限

API 键使用与用户帐户相同的基于角色的访问控制（RBAC）系统。当通过 Web 应用程序或 API 创建或管理键时，您在两个级别上分配角色：

组织角色 — 定义键的整个组织的基线权限（例如， org_admin 或 org_member).
应用角色 — 应用程序权限（例如， app_admin, app_developer, app_uploader, app_reader或 app_preview).

如果一个 API 键具有显式角色绑定， 仅这些绑定 在权限检查中被评估。关键所有者的个人权限不会被关键继承。

预览频道自动化

仅绑定到创建临时、非公共预览频道的CI应用，上传并推广一个包，然后删除两者。 app_preview 复制到剪贴板

{
  "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 是应用记录的内部UUID，而不是__CAPGO_KEEP_0__命令中使用的公共应用标识符（例如， app_id is the app record’s internal UUID, not the public app identifier used by CLI commands (for example, com.example.app应用级别

角色仅包括 app_preview ,和 app.read, app.read_bundles, app.upload_bundleCopy to clipboard app.create_channelWhen that key creates a channel, Capgo 自动添加一个 channel_preview 绑定到新创建的通道上。该子绑定仅授予 channel.read, channel.promote_bundle和 channel.delete 对创建该通道的 key 所有。该 key

app_preview 保留 app.read，因此这不是严格的通道读取隔离：该 key 可以枚举该 key 选择的应用程序的通道元数据。自动子绑定限制 生命周期变更 到该 key 创建的通道。__CAPGO_KEEP_0__ 记录了每个应用程序预览 key 上传的每个捆绑包。该 key 只能将其自己的捆绑包推送到它创建的每个预览通道中。它对现有的默认/主通道、由另一个预览 key 创建的通道或另一个 key 的捆绑包没有通道生命周期访问权限。对于此工作流程，请忽略

Capgo records the App Preview key that uploaded each bundle. The key can promote only its own bundle to each preview channel it creates. It has no channel lifecycle access to an existing default/main channel, a channel created by another preview key, or another key’s bundle. For this workflow, omit public 使用 --default.

进行清理。该清理路由是原子且拥有权检查的预览清理路由；它只删除调用该 key 的预览通道和关联的捆绑包。 channel delete <preview-channel> <public-app-id> --delete-bundle for cleanup. This is an atomic, ownership-checked preview cleanup route; it removes only the calling key’s preview channel and linked bundle. app_preview 不提供通用授权 bundle.delete.

对于仪表板设置和完整的CLI示例，请参阅使用 App 预览密钥预览工作流.

组织创建权限

Creating organizations with an API key now uses an explicit global permission: org.create.

此权限与正常的 org/app 角色绑定分开，因为新组织在创建时尚未存在 POST /organization/ 被称为。要创建具有API密钥的组织：

API密钥必须包含 org.create 在 global_permissions.
同一个API密钥也必须具有当前组织范围的 org_admin 或 org_super_admin 绑定。
新API密钥默认不会接收 org.create 启用 允许创建组织 当在仪表板中创建或编辑RBACAPI密钥时
现有的写入可组织管理员/超级管理员API密钥已被补充 org.create 以便现有的集成可以继续创建组织。

When an API key creates an organization, Capgo automatically assigns that same API key as org_super_admin 在创建组织时，__CAPGO_KEEP_1__会自动将同样的__CAPGO_KEEP_2__密钥分配给

If you create an API key through the API, include global_permissions 创建组织时，__CAPGO_KEEP_0__密钥通过__CAPGO_KEEP_1__创建，包括

{
  "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 Copy to clipboard org_super_admin.

仅适用于创建组织。删除组织仍然需要在目标组织上拥有删除权限，通常通过

安全（散列）密钥

When creating a secure key, the server generates the key material and returns the plain-text value once. Only a hash is stored. This means: 在创建安全密钥时，服务器会生成密钥材料并返回一次明文值。只存储散列值。这意味着： The plain-text key、cannot be retrieved、after creation.
__CAPGO_KEEP_0__产生一个新的纯文本密钥（只显示一次）并更新存储的哈希值。
建议在生产环境中使用哈希密钥。

某些组织通过 enforce_hashed_api_keys org策略强制使用哈希密钥。

过期

密钥可以有一个可选的过期日期。过期密钥在权限检查层面会被拒绝。

组织策略可以强制：

强制过期 (require_apikey_expiration） — 所有新密钥必须具有过期时间。
最大TTL (max_apikey_expiration_days） — 过期时间不能超过N天。

安全最佳实践

最小特权原则: 为您的集成分配最少权限的角色
定期轮换: 使用重生成功能定期轮换您的 API 密钥
安全存储: 安全地存储 API 密钥并且不要将其提交到版本控制
使用散列密钥: 为生产集成创建安全的（散列）密钥
设置过期时间: 总是为临时或 CI/CD 访问的密钥设置过期日期
作用域限制: 限制密钥仅在特定应用中使用，且仅允许最低权限角色

常见用例

CI/CD 集成: 创建密钥，仅在特定应用中使用，且仅允许最低权限角色，并设置过期时间 app_uploader 或 app_developer 预览频道
: 在 CI 需要上传包时，仅在预览应用或应用中使用，创建临时频道，并原子性地清除频道和包部署自动化 app_preview __CAPGO_KEEP_0__
__CAPGO_KEEP_0__: 使用密钥与 app_developer 角色为自动部署脚本。
监控工具: 创建密钥与 app_reader 角色为外部监控集成。
管理员访问: 使用密钥与 org_admin 角色谨慎使用管理员工具。
第三方集成: 创建密钥仅限特定应用程序，使用最少的所需角色。
组织配置: 使用密钥与 org_admin 或 org_super_admin RBAC密钥 org.create 仅用于信任的自动化，需要创建组织的。

从API Keys继续

如果您正在使用 API Keys 来规划身份验证和帐户流程，连接它 @capgo/capacitor-social-login 查看@capgo/capacitor-social-login的实现细节 @capgo/capacitor-passkey 查看@capgo/capacitor-passkey的实现细节 @capgo/capacitor-native-biometric 查看 @capgo/capacitor-native-biometric 的实现细节双因素认证查看双因素认证的实现细节企业级 SSO 查看企业级 SSO 的实现细节