Authentication

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

Rate limit headers are included in all responses:

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.

Getting Started

Status Management

Monitoring

Alerting

Automation

Notifications

Client Tracking

Integrations

Authentication

API Keys

Getting Your API Key

Scoped API Keys

Available Scopes

Scope Enforcement

Environment Variables

Rate Limits

Endpoints Outside `/api/v1`

​API Keys

​Getting Your API Key

​Scoped API Keys

​Available Scopes

​Scope Enforcement

​Environment Variables

​Rate Limits

​Endpoints Outside /api/v1

API Keys

Getting Your API Key

Scoped API Keys

Available Scopes

Scope Enforcement

Environment Variables

Rate Limits

Endpoints Outside `/api/v1`