API 键

API 密钥用于验证对 Capgo API 的请求。每个密钥可以有不同的权限（模式）来控制访问级别。密钥是特定于组织的，应谨慎管理，因为它们授予对 Capgo 资源的访问权限。

关键模式

读取：只能读取数据，不允许修改
上传：可以读取、修改和上传新包
写入：可以读取、修改数据和上传包
全部：对所有操作的完全访问权限

关键模式遵循逐步/渐进的模式。如果您有上传密钥，然后创建写入密钥，则写入密钥将能够执行上传密钥可以执行的所有操作。请查看下图以更好地了解 API 键的工作原理。

具有有限权限的子项

您可以创建对特定应用程序或组织具有有限访问权限的子项。这对于限制对某些资源的访问同时仍然允许对其他资源进行操作非常有用。创建密钥时使用 limited_to_apps 和 limited_to_orgs 参数来定义这些限制。

加密密钥

您可以创建加密（散列）API 密钥以增强安全性。创建加密密钥时：

密钥在存储到数据库之前使用 SHA-256 进行哈希处理
明文密钥在创建响应中仅返回一次 - 立即保存
密钥创建后无法再次检索或查看
如果您丢失了加密密钥，则必须创建一个新密钥

创建密钥以启用加密时，请使用 hashed: true 参数。这是生产环境的推荐方法。

密钥过期

API 密钥可以有一个到期日期，以限制密钥被泄露时的暴露时间。当设置了到期日期时：

钥匙在指定的日期和时间后停止工作
使用过期密钥的请求将被拒绝并出现错误
过期密钥将在 30 天后自动清除

组织可以强制执行过期策略：

需要过期：所有 API 密钥必须有过期日期
最大到期期限：限制可以设置的到期日期

安全最佳实践

最小权限原则：始终使用仍允许您的集成正常运行的最严格的模式
使用加密密钥：为生产创建散列密钥以防止数据库泄露
设置到期日期：使用到期日期来限制密钥的生命周期
定期轮换：定期轮换您的 API 钥匙
安全存储：安全存储 API 密钥，切勿将其提交给版本控制
监控：监控 API 密钥使用情况并立即撤销任何受损密钥
有限子密钥：使用具有有限权限的子密钥进行特定集成，以最大程度地降低风险

端点

获取

https://api.capgo.app/apikey/

检索与您的帐户关联的所有 API 密钥。

响应类型

interface ApiKey {
  created_at: string | null
  id: number
  key: string | null  // null for encrypted keys
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  expires_at?: string | null  // ISO 8601 date, null means never expires
}
```> **注意**：对于加密密钥，GET 响应中的 `key` 字段将为 `null`，因为纯密钥在创建过程中仅显示一次。

#### 请求示例

```bash
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/

响应示例

{
  "data": [
    {
      "id": 1,
      "key": "ak_123...",
      "mode": "read",
      "name": "CI/CD Read Key",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "user_id": "user_123"
    },
    {
      "id": 2,
      "key": "ak_456...",
      "mode": "upload",
      "name": "Deploy Bot",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "user_id": "user_123",
      "limited_to_apps": ["com.demo.app"]
    }
  ]
}

发布

https://api.capgo.app/apikey/

为特定组织创建新的 API 密钥。

请求正文

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  hashed?: boolean       // Create an encrypted key (recommended for production)
  expires_at?: string    // ISO 8601 date for key expiration
}

请求示例（标准密钥）

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Read Key",
    "mode": "read",
    "limited_to_apps": ["com.demo.app"]
  }' \
  https://api.capgo.app/apikey/

请求示例（带有效期的加密密钥）

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure CI Key",
    "mode": "upload",
    "hashed": true,
    "expires_at": "2025-06-01T00:00:00Z"
  }' \
  https://api.capgo.app/apikey/

响应示例（标准密钥）

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "Limited Read Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "limited_to_apps": ["com.demo.app"]
  }
}

响应示例（加密密钥）

{
  "apikey": {
    "id": 4,
    "key": "ak_abc123...",
    "mode": "upload",
    "name": "Secure CI Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "expires_at": "2025-06-01T00:00:00Z"
  }
}

重要：对于加密密钥，此响应中的 key 值是您唯一一次看到明文密钥。立即将其保存在安全的位置。后续 GET 请求将为 key 字段返回 null。

删除

https://api.capgo.app/apikey/:id/

删除现有的 API 密钥。使用它可以立即撤销访问权限。

参数

id：要删除的 API 密钥的 ID（数字标识符，而不是密钥字符串本身）

请求示例

curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/

成功响应

{
  "success": true
}

常见用例

CI/CD集成：为CI管道创建只读密钥以检查部署状态
部署自动化：使用上传模式密钥进行自动化部署脚本
监控工具：使用读取模式键进行外部监控集成
管理员访问：谨慎使用所有模式键作为管理工具
有限访问：创建对特定应用程序或组织具有有限权限的子项以进行第三方集成

错误处理

常见错误场景及其应对措施：

// Invalid mode
{
  "error": "Invalid mode specified. Must be one of: read, write, upload, all",
  "status": "KO"
}

// Key not found
{
  "error": "API key not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage API keys",
  "status": "KO"
}

// Expired API key used for authentication
{
  "error": "API key has expired",
  "status": "KO"
}

// Invalid expiration date (in the past)
{
  "error": "Expiration date must be in the future",
  "status": "KO"
}

// Organization requires expiration
{
  "error": "Organization policy requires an expiration date for API keys",
  "status": "KO"
}

// Expiration exceeds organization limit
{
  "error": "Expiration date exceeds organization maximum of 90 days",
  "status": "KO"
}