API Keys

API keys are used to authenticate requests to the Capgo API. Each key can have different permissions (modes) to control access levels. Keys are organization-specific and should be managed carefully as they grant access to your Capgo resources.

Key Modes

• read: Can only read data, no modifications allowed
• write: Can read and modify data, but cannot upload new bundles
• upload: Can read, modify, and upload new bundles
• all: Full access to all operations

Security Best Practices

1. Principle of Least Privilege: Always use the most restrictive mode that still allows your integration to function
2. Regular Rotation: Rotate your API keys periodically
3. Secure Storage: Store API keys securely and never commit them to version control
4. Monitoring: Monitor API key usage and revoke any compromised keys immediately

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
}

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

POST

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

Create a new API key for a specific organization.

Query Parameters

interface ApiKeyCreate {
  org_id: string
  mode: 'read' | 'write' | 'upload' | 'all'
}

Example Request

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_123",
    "mode": "read"
  }' \
  https://api.capgo.app/apikey/

Example Response

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "New API Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123"
  }
}

DELETE

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

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

Parameters

• key: The API key to delete (the UUID-like string) or the id of the API key

Example Request

# Delete by key
curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/ak_123.../

# Delete by ID
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

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