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 权限

使用 __CAPGO_KEEP_0__ 键']}

API keys 使用相同的基于角色的访问控制 (RBAC) 系统来管理用户账户。通过 web 应用程序创建或管理密钥时，您可以在两个级别Assign 角色：

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

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

安全（散列）密钥

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

明文密钥 无法在创建后恢复。 重新生成会产生一个新的明文密钥（只显示一次）并更新存储的散列。
散列密钥适用于生产环境的推荐。
一些组织通过

组织策略 enforce_hashed_api_keys 强制使用散列密钥。

过期

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

__CAPGO_KEEP_0__. 可以强制执行：

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

安全最佳实践

最小权限原则: 将分配给你的集成的最具限制性的角色
定期轮换: Rotate your API keys periodically using the regenerate feature
安全存储: Store API keys securely and never commit them to version control
使用哈希密钥: 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 集成: 根据特定应用创建作用域的密钥，并设置过期日期 app_uploader 或 app_developer 角色
自动化部署: 使用密钥 app_developer 角色
自动化部署脚本: 为外部监控集成创建密钥 app_reader 角色
监控工具: 使用密钥 org_admin 角色谨慎使用，仅用于管理工具
第三方集成: 使用最低权限角色创建受特定应用限制的密钥