API 密钥

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

密钥模式

• read: 只能读取数据,不允许修改
• upload: 可以读取、修改和上传新 bundle
• write: 可以读取、修改数据和上传 bundle
• all: 对所有操作的完全访问权限

密钥模式遵循阶梯式/渐进式架构。如果您有上传密钥,然后创建写入密钥,写入密钥将能够执行上传密钥可以执行的所有操作。 请查看以下图表以更好地了解 API 密钥的工作原理。

具有受限权限的子密钥

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

安全最佳实践

1. 最小权限原则: 始终使用仍允许集成运行的最严格模式
2. 定期轮换: 定期轮换您的 API 密钥
3. 安全存储: 安全存储 API 密钥,切勿将它们提交到版本控制
4. 监控: 监控 API 密钥使用情况并立即撤销任何受损的密钥
5. 受限子密钥: 对特定集成使用具有受限权限的子密钥以最小化风险

Endpoints

GET

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

Retrieve all API keys associated with your account.

Response Type

interface ApiKey {
  created_at: string | null
  id: number
  key: string
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
}

Example Request

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

Example Response

{
  "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"]
    }
  ]
}

POST

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

Create a new API key for a specific organization.

Query Parameters

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
}

Example Request

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/

Example Response

{
  "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"]
  }
}

DELETE

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

Delete an existing API key. Use this to revoke access immediately.

Parameters

• id: The ID of the API key to delete (numeric identifier, not the key string itself)

Example Request

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

Success Response

{
  "success": true
}

Common Use Cases

1. CI/CD Integration: Create read-only keys for CI pipelines to check deployment status
2. Deployment Automation: Use upload mode keys for automated deployment scripts
3. Monitoring Tools: Use read mode keys for external monitoring integrations
4. Admin Access: Use all mode keys sparingly for administrative tools
5. Limited Access: Create subkeys with limited rights to specific apps or organizations for third-party integrations

Error Handling

Common error scenarios and their responses:

// 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"
}