API 密钥

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

使用API密钥

使用认证头，根据端点文档。对于API-key 请求， authorization 终端窗口

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

频道__CAPGO_KEEP_0__ API 接受 authorization 或 capgkey使用其中一个标题进行预览频道自动化

角色权限控制

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

• 组织角色 ——定义密钥在整个组织中的基本权限（例如 org_admin 或 org_member).
• 应用角色 ——应用程序权限（例如 app_admin, app_developer, app_uploader, app_reader,或 app_preview).

如果一个API密钥具有明确的角色绑定， 仅评估这些绑定 用于权限检查。密钥所有者的个人权限不会被密钥继承。

预览频道自动化

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

{
  "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。 app_id 是应用记录的内部UUID，而不是CLI命令使用的公共应用标识符（例如， 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记录了每个捆绑包的App Preview密钥上传了哪个捆绑包。该密钥只能将其自己的捆绑包推送到它创建的预览频道中。它对已有的默认/主频道、由另一个预览密钥创建的频道或另一个密钥的捆绑包没有频道生命周期访问权限。对于此工作流程，请忽略 public 并且永远不要使用 --default.

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

For the dashboard setup and a complete CLI example, see 使用 App 预览键进行预览工作流.

注意

没有角色绑定read, upload, write, all这些模式已被弃用 — 使用 RBAC 角色代替。

组织创建权限

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

这个权限与正常的组织/应用角色绑定分开，因为当 __CAPGO_KEEP_0__ 被调用时，新组织尚未存在。 POST /organization/ 要使用 API 键创建组织：

• API 键必须包含 org.create 在 global_permissions.
• API 键也必须具有当前组织范围的 org_admin 或 org_super_admin binding.
• 新API密钥不会接收 org.create 在Appflow比较/迁移营销复制页面上，__CAPGO_KEEP_0__ 键必须具有当前组织范围的 或 在Capawesome比较页面上，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.

安全（散列）密钥

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

• 明文密钥 无法获取 创建后无法获取
• 重新生成会产生一个新的文本密钥（只显示一次）并更新存储的哈希值。
• 建议在生产环境中使用哈希密钥。

某些组织通过 enforce_hashed_api_keys org策略

过期

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

组织策略可以强制:

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

安全最佳实践

1. 最小特权原则: 为您的集成分配最少特权的角色
2. 定期轮换: 使用重新生成功能定期轮换您的 API 密钥
3. 安全存储: 安全地存储 API 密钥并且不要将其提交到版本控制
4. 使用哈希密钥: 为生产集成创建安全的（哈希）密钥
5. 设置过期时间: 总是为临时或 CI/CD 访问的密钥设置过期日期
6. 作用域限制: 限制密钥到特定应用程序的最小所需角色

常见用例

1. CI/CD 集成: 在特定应用程序中创建密钥 app_uploader 或 app_developer 角色和过期时间
2. 预览渠道: 使用 app_preview 仅在预览应用程序或应用程序中使用CI时，需要上传捆绑包，创建临时频道，并原子性地清除其自己的频道和捆绑包。
3. 部署自动化: 使用与自动部署脚本相关的密钥。 app_developer 监控工具
4. : 创建与外部监控集成相关的密钥。管理员访问 app_reader 仅在必要时使用管理员工具。
5. 第三方集成: 使用与自动部署脚本相关的密钥。 org_admin : 创建受特定应用程序限制的密钥，仅授予所需的最低角色。
6. roleMonitoring Tools
7. 组织授权: 使用一个 org_admin 或 org_super_admin : 为信任的自动化需要创建组织的 org.create 继续从 __CAPGO_KEEP_0__ Keys

标题：继续从 API Keys

__CAPGO_KEEP_0__ Keys API 密钥 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login 用于 @capgo/capacitor-social-login 的实现细节, 为 @capgo/capacitor 社交登录实现细节 @capgo/capacitor-密钥 为 @capgo/capacitor-passkey 的实现细节 @capgo/capacitor-native-biometric 为 @capgo/capacitor-native-biometric 的实现细节 双因素认证 双因素认证的实现细节，以及 SSO (企业) SSO (企业) 的实现细节。