API 密钥

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

使用一个 API 键

将您的 API 密钥传递到 x-api-key 请求头中：

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

请求头也被接受，但主要用于 JWT令牌。当值为 UUID 格式的 __CAPGO_KEEP_0__ 密钥时它有效，但 authorization header is also accepted but is primarily intended for JWT tokens. When the value is a UUID-formatted API key it works, but x-api-key RBAC 权限

部分：RBAC 权限

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app, you assign roles at two levels:

Section titled “Using an __CAPGO_KEEP_0__ key” — 定义了整个组织中密钥的基线权限（例如 org_admin, org_member).
应用角色 — 可选的每个应用的权限（例如 app_admin, app_developer, app_uploader, app_reader).

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

创建组织的权限

使用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 允许创建组织 允许创建组织 When creating or editing an RBAC API key in the dashboard.
现有的可写组织管理员/超级管理员 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 无法在创建后检索到 生成新文本密钥（仅显示一次）并更新存储的哈希值
建议在生产环境中使用哈希密钥
某些组织通过

org 政策强制使用哈希密钥 enforce_hashed_api_keys 过期

标题：过期

组织政策可以强制：

必须过期的密钥

必须过期 (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

常见用例

CI/CD 集成: Create keys scoped to specific apps with the app_uploader 或 app_developer role, and set an expiration date
部署自动化: 使用 __CAPGO_KEEP_0__ 以及其他密钥 app_developer 用于自动化部署脚本
监控工具: 创建 __CAPGO_KEEP_0__ 以及其他密钥 app_reader 用于外部监控集成
管理员访问: 使用 __CAPGO_KEEP_0__ 以及其他密钥 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-生物识别对于 @capgo/capacitor-native-生物识别的实现细节, 双因素认证对于双因素认证的实现细节, 和 SSO (企业) 对于 SSO (企业) 的实现细节。