API密钥

API 键用于验证请求到 Capgo API 的请求。这些密钥是组织特有的，可以为细粒度访问控制分配 RBAC 角色。每个密钥也可以具有可选的过期日期，并且可以以“安全”（散列）形式创建密钥，其中明文值只显示一次。

使用 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密钥具有明确的角色绑定 仅评估这些绑定以进行权限检查。密钥所有者的个人权限不会被密钥继承。 预览频道自动化

预览频道自动化

复制到剪贴板 app_preview 是应用所有者的组织的UUID

{
  "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_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_bundle, 和 app.create_channel. 当该密钥创建一个频道时,Capgo会自动在新创建的频道上添加一个 channel_preview 绑定。该子绑定授予 channel.read, channel.promote_bundle, 和 channel.delete 仅限于该密钥创建的频道。

app_preview 保留 app.read, 因此这不是严格的频道读取隔离：密钥可以枚举所选应用的频道元数据。自动子绑定限制了 生命周期变更 仅限于该密钥创建的频道。

Capgo记录了每个应用预览密钥上传的应用包。该密钥只能将其自己的应用包推送到它创建的每个预览频道。它没有对现有默认/主频道、由另一个预览密钥创建的频道或另一个密钥的应用包的频道生命周期访问权限。对于此工作流程，请忽略 public 并且绝不使用 --default.

使用 channel delete <preview-channel> <public-app-id> --delete-bundle 用于清理。该清理路由是原子性的，拥有者检查的预览清理路由；它只移除调用密钥的预览频道和关联的包。 app_preview 不授予通用 bundle.delete.

有关仪表板设置和完整的CLI示例，请参见 使用应用预览密钥进行预览工作流.

注意

没有角色绑定的密钥会回退到基于模式的遗留系统（read, upload, write, all这些模式已被弃用 — 使用RBAC角色代替。

组织创建权限

使用API密钥创建组织现在需要显式全局权限: org.create.

此权限与正常的组织/应用角色绑定分开，因为当调用时，新组织尚未存在。 POST /organization/ 要使用API密钥创建组织:

• API密钥必须包含 org.create 在 global_permissions.
• API密钥也必须具有当前组织范围的 org_admin 或 org_super_admin __CAPGO_KEEP_0__密钥必须具有当前组织范围的
• API密钥必须具有当前组织范围的 org.create __CAPGO_KEEP_0__密钥必须具有当前组织范围的 允许创建组织 当在控制台中创建或编辑 RBAC API 密钥时。
• 已有的可写组织管理员/超级管理员 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.

安全（散列）密钥

创建安全密钥时，服务器会生成密钥材料并返回一次明文值。只存储散列。这意味着：

• The plain-text key 无法从创建后检索 。
• 重新生成会产生一个新的文本密钥（只显示一次）并更新存储的哈希值。
• 建议在生产环境中使用哈希密钥。

某些组织通过 enforce_hashed_api_keys 组织策略

过期

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

组织策略可以强制执行：

• 强制过期 (require_apikey_expiration) — 所有新建的密钥必须有一个过期时间。
• 最大有效期 (max_apikey_expiration_days) — 过期时间不能超过 N 天。

安全最佳实践

1. 最小特权原则: 为您的集成分配最少权限的角色，仍然允许其正常工作
2. 定期轮换: 使用重新生成功能定期轮换您的 API 密钥
3. 安全存储: 安全存储 API 密钥，并且不要将其提交到版本控制中
4. 使用哈希密钥: Create secure (hashed) keys for production integrations
5. 设置过期时间: Always set an expiration date on keys used for temporary or CI/CD access
6. : Restrict keys to specific apps with the minimum required role: Create keys scoped to specific apps with the

或

1. CI/CD 集成: Create keys scoped to specific apps with the minimum required role and set an expiration date. app_uploader : Create keys scoped to specific apps with the minimum required role and set an expiration date. app_developer : Create keys scoped to specific apps with the minimum required role and set an expiration date.
2. : Create keys scoped to specific apps with the minimum required role and set an expiration date.: 使用 app_preview 仅在 CI 需要上传包时，在预览应用或应用中使用。
3. 部署自动化: 使用带有 app_developer 角色的密钥来自动化部署脚本。
4. 监控工具: 为外部监控集成创建带有 app_reader 角色的密钥。
5. 管理员访问: 使用带有 org_admin 角色的密钥谨慎使用管理员工具。
6. 第三方集成创建受特定应用程序限制的密钥，仅允许最低权限角色。
7. 组织配置使用一个 org_admin 或 org_super_admin 继续从__CAPGO_KEEP_0__密钥 org.create 继续从__CAPGO_KEEP_0__密钥

如果您正在使用API密钥

连接它 API/__CAPGO_KEEP_1__-social-login RBAC密钥 @capgo/capacitor-social-login 为 @capgo/capacitor 社交登录实现细节 @capgo/capacitor 传统密码 为 @capgo/capacitor 传统密码实现细节 @capgo/capacitor 本机生物识别 为 @capgo/capacitor 本机生物识别实现细节 双因素认证 为双因素认证和 企业SSO 为企业SSO实现细节