API Keys
All API requests require authentication using an API key. Include your key in the X-API-Key header:
curl "https://kodostatus.com/api/v1/incidents" \
-H "X-API-Key: your_api_key_here"
Getting Your API Key
- Log in to your Dashboard
- Navigate to Settings > API
- Click Generate API Key
- Copy and securely store your key
API keys grant full access to your organization. Keep them secret and never commit them to version control.
Scoped API Keys
For fine-grained access control, create scoped API keys with specific permissions. This is recommended for CI/CD pipelines, integrations, and service accounts.
- Go to Settings > API Keys in your dashboard
- Click Create Key
- Name your key and select the required scopes
- Optionally set an expiry date
- Copy the key immediately — it won’t be shown again
Available Scopes
| Scope | Description |
|---|
*:* | Full access (default) |
incidents:read | List and view incidents |
incidents:write | Create, update, delete incidents |
services:read | List and view services |
services:write | Create, update, delete services |
status_pages:read | List and view status pages |
status_pages:write | Manage status pages and designs |
monitors:read | View uptime, SSL, and domain monitors |
monitors:write | Manage monitors |
maintenance:read | View maintenance windows |
maintenance:write | Manage maintenance windows |
notifications:read | View notification channels and webhooks |
notifications:write | Manage channels and webhooks |
config:read | Read organization configuration |
config:write | Update configuration |
heartbeat:write | Send heartbeat pings |
metrics:write | Push metrics data |
workflows:write | Trigger workflows |
audit_log:read | Read the audit log |
Scope Enforcement
When a scoped key attempts an action it doesn’t have permission for, the API returns:
{
"error": "Insufficient scope: incidents:write required"
}
Legacy API keys (from Settings > API) retain full *:* access for backwards compatibility.
Environment Variables
We recommend storing your API key in environment variables:
# .env
KODO_API_KEY="your_api_key_here"
Rate Limits
| Endpoint | Limit |
|---|
| Standard endpoints | 1,000 requests/minute |
| Heartbeat endpoint | 10,000 requests/minute |
| Beacon endpoint | No limit |
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704844800
Endpoints Outside /api/v1
Some endpoints live at /api/ instead of /api/v1/ and use their own authentication:
POST /api/heartbeat/:monitorId - Send heartbeat pings (API key in header)GET /api/heartbeat/:monitorId - Check heartbeat status (API key in header)POST /api/beacon - Report client-side events (beacon public key in body)POST /api/metrics/ingest - Push metrics (API key in header)
All of these endpoints require authentication via the X-API-Key header or Authorization: Bearer header, except the beacon endpoint which uses a beacon public key (bpk_...) in the request body.
