Scoped API Keys

​

Overview

• CI/CD Pipeline: incidents:write only — can create incidents but can’t read services
• Dashboard Widget: incidents:read, services:read — read-only access for displays
• Monitoring Agent: heartbeat:write, metrics:write — can send data but can’t modify anything

​

Creating a Key

​

Via Dashboard

1. Navigate to Settings > API Keys
2. Click Create Key
3. Enter a descriptive name
4. Select the permissions your key needs
5. Optionally set an expiry date
6. Click Create Key
7. Copy the key immediately — it will only be shown once

​

Via API

curl -X POST "https://kodostatus.com/api/v1/api-keys" \
  -H "X-API-Key: your_full_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["incidents:write"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

{
  "id": "uuid",
  "name": "CI/CD Pipeline",
  "key": "kodo_abc123...",
  "key_prefix": "kodo_abc123..",
  "scopes": ["incidents:write"],
  "enabled": true,
  "created_at": "2026-02-21T00:00:00Z"
}

​

Managing Keys

​

List Keys

curl "https://kodostatus.com/api/v1/api-keys" \
  -H "X-API-Key: your_api_key"

​

Disable a Key

curl -X PATCH "https://kodostatus.com/api/v1/api-keys/{id}" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

​

Delete a Key

curl -X DELETE "https://kodostatus.com/api/v1/api-keys/{id}" \
  -H "X-API-Key: your_api_key"

​

Plan Limits

​

Best Practices

• Principle of least privilege: Give each key only the scopes it needs
• Set expiry dates: Rotate keys regularly, especially for CI/CD
• Use descriptive names: Name keys after their purpose (e.g., “GitHub Actions Deploy”)
• Monitor usage: Check last_used_at to identify unused keys
• Disable before deleting: Disable a key first to verify nothing breaks before permanent removal