API密钥

复制安装步骤和本插件的完整Markdown指南的设置提示

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

使用API密钥

使用API-密钥请求时，应遵循以下步骤： authorization Terminal 窗口

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

__CAPGO_KEEP_1__ 频道 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_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示例，请参见使用应用预览密钥进行预览工作流.

组织创建权限

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

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

API密钥必须包含 org.create 在 global_permissions.
API密钥也必须具有当前组织范围的 org_admin 或 org_super_admin __CAPGO_KEEP_0__密钥
New API keys do not receive 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 cannot be retrieved after creation.
Regeneration produces a new plain-text key (shown once) and updates the stored hash.
Hashed keys are recommended for production use.

Some organizations enforce hashed keys via the enforce_hashed_api_keys org policy.

Expiration

Keys can have an optional expiration date. Expired keys are rejected at the permission check layer.

Organization policies can enforce:

Mandatory expiration (require_apikey_expiration) — 所有新密钥必须具有过期时间。
最大有效期 (max_apikey_expiration_days) — 过期时间不能超过 N 天。

安全最佳实践

最小特权原则: 为您的集成分配最少特权的角色，仍然允许其正常工作
定期轮换: 使用重新生成功能定期轮换您的 API 密钥
安全存储: 安全存储 API 密钥，并且不要将其提交到版本控制
使用哈希密钥：创建安全（散列）密钥用于生产集成
设置过期时间：始终为临时或 CI/CD 访问设置密钥的过期日期
作用域限制：限制密钥到特定应用程序的最小必需角色

常见用例

：创建针对特定应用程序的密钥或 app_uploader PR 预览频道 app_developer ：创建针对特定应用程序的密钥并设置过期日期
常见用例: 使用 app_preview 仅在 CI 需要上传包时，在预览应用或应用中使用。
部署自动化: 使用具有 app_developer 角色的密钥来自动化部署脚本。
监控工具: 为外部监控集成创建具有 app_reader 角色的密钥。
管理员访问: 使用具有 org_admin 角色的密钥谨慎使用管理员工具。
第三方集成: 在创建需要特定应用程序的最低权限的密钥。
组织授权: 使用一个 org_admin 或 org_super_admin : 在Capacitor live-update替代方案比较页面上，使用一个 org.create 或

Keep going from API Keys

: 在咨询服务页面上，使用一个 API Keys : 在Appflow比较/迁移营销复制页面上，使用一个 @capgo/capacitor-social-login 为 @capgo/capacitor-social-login 的实现细节 @capgo/capacitor-passkey 为 @capgo/capacitor-passkey 的实现细节 @capgo/capacitor-native-biometric 为 @capgo/capacitor-native-biometric 的实现细节双因素认证双因素认证的实现细节，以及企业级单点登录 (SSO) 企业级单点登录 (SSO) 的实现细节。