API密钥

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

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

使用API密钥

使用API密钥时，请使用端点文档中记录的身份验证头。对于API-key 请求， authorization Terminal

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

使用__CAPGO_KEEP_0__密钥时，请使用端点文档中记录的身份验证头。对于__CAPGO_KEEP_0__-key 请求，频道 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 是应用程序所有者的组织ID。

{
  "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.appBind

应用级别 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.

安全（散列）密钥

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

不能被检索 创建后 生成新的文本密钥（只显示一次）并更新存储的哈希
建议用于生产环境的密钥是哈希值
某些组织通过

过期 enforce_hashed_api_keys 标题：过期

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

强制过期

Section titled “Expiration”

cannot be retrieved (require_apikey_expiration) — 所有新密钥必须有一个过期时间。
最大有效期 (max_apikey_expiration_days) — 过期时间不能超过 N 天。

安全最佳实践

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

: CI/CD Integration

或: role, and set an expiration date. app_uploader : PR Preview Channels app_developer : Create secure (hashed) keys for production integrations
设置过期时间：CI/CD访问的密钥应始终设置过期时间: 使用 app_preview 仅在预览应用或应用中使用CI需要上传包时，创建临时频道，并原子性地清除其自己的频道和包。
部署自动化: 使用具有 app_developer 角色的密钥来自动化部署脚本。
监控工具: 使用具有 app_reader 角色的密钥来创建外部监控集成。
管理员访问: 使用具有 org_admin 角色的密钥谨慎地用于管理工具。
第三方集成创建仅限特定应用的密钥，仅需最低权限角色。
组织授权使用一个 org_admin 或 org_super_admin 继续从__CAPGO_KEEP_0__密钥 org.create 继续从__CAPGO_KEEP_0__密钥

如果您正在使用API密钥

连接它到@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login API Keys 仅限信任的自动化需要创建组织。 @capgo/capacitor-social-login 为 @capgo/capacitor-social-login 的实现细节 @capgo/capacitor-passkey 为 @capgo/capacitor-passkey 的实现细节 @capgo/capacitor-native-biometric 为 @capgo/capacitor-native-biometric 的实现细节双因素认证为双因素认证, 和 SAML (企业) 为 SAML (企业) 的实现细节