API 密钥

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

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

使用一个 API 密钥

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

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

这个 authorization 标题也可以接受，但主要是用于 JWT令牌。当值是 UUID 格式的 API 键时它有效，但 x-api-key 是所有键类型（包括安全/散列密钥）的推荐标题。

RBAC 权限

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

组织角色 —— 定义密钥的基线权限范围整个组织（例如 org_admin, org_member).
应用角色 —— 可选的每个应用程序权限（例如 app_admin, app_developer, app_uploader, app_reader).

如果一个 API 密钥有明确的角色绑定, 只有那些绑定 这些绑定

创建组织权限

使用 API 密钥创建组织现在使用一个显式的全局权限： org.create.

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

The API key必须包含 org.create 在 global_permissions.
The same API key也必须具有当前组织范围的 org_admin 或 org_super_admin 绑定。
新API密钥不默认接收 org.create 通过启用 允许创建组织 当在控制台中创建或编辑RBACAPI密钥时
现有的写入可组织管理员/超级管理员API密钥已回填 org.create 以便现有的集成可以继续创建组织

当API密钥创建组织时,Capgo自动将同一个API密钥赋予 org_super_admin On新创建的组织。这让集成管理它刚刚创建的组织，而不需要单独的手动角色绑定。

If您通过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 过期

标题：过期

组织策略可以强制要求：

强制过期

）—所有新密钥必须具有过期时间。 (require_apikey_expiration最大TTL
）—过期时间不能超过N天。 (max_apikey_expiration_days安全最佳实践

Security Best Practices

最小特权原则: 为您的集成分配最少权限的角色
定期轮换: 使用重生成功能定期轮换您的 API 密钥
安全存储: 安全地存储 API 密钥并且不要将其提交到版本控制
使用哈希密钥: 为生产集成创建安全的（哈希）密钥
设置过期时间: 总是为临时或 CI/CD 访问的密钥设置过期日期
权限范围限制: 仅允许特定应用程序访问密钥,并且必须具有最低权限

常见用例

CI/CD 集成: 为特定应用程序创建密钥,并且必须具有特定的 app_uploader 或 app_developer 角色，并设置过期日期
部署自动化: 使用具有特定 app_developer 角色来自动化部署脚本
监控工具: 为密钥创建 app_reader 用于外部监控集成的角色
管理员访问：使用 org_admin 角色
外部监控集成角色
外部监控集成角色 org_admin 外部监控集成 org_super_admin 角色 org.create 外部监控集成

Keep going from API Keys

如果您正在使用 API Keys 来规划身份验证和帐户流程，连接它与 @capgo/capacitor-social-login 关于在 @capgo/capacitor-social-login 中的实现细节， @capgo/capacitor-passkey 关于在 @capgo/capacitor-passkey 中的实现细节， @capgo/capacitor-native-biometric 关于在 @capgo/capacitor-native-biometric 中的实现细节，双因素身份验证关于在双因素身份验证中的实现细节， [SSO (Enterprise)](https://capgo.com/docs/sso-enterprise) 关于 [SSO (Enterprise)](https://capgo.com/docs/sso-enterprise) 的实现细节。