API Authentication

This page covers the public REST API (/api/v1/*) — the one your own scripts, CI pipelines, or integrations call. It’s separate from the browser login flow you use to sign into the dashboard (that one runs on Keycloak/OIDC behind the scenes and isn’t something API clients need to deal with).

Requirements

The public API is gated to the Max plan. The Prometheus export is available from Pro, with a Metrics key.

Access levels

Each key gets one access level when it’s created, and keeps it when rotated:

Access	What it can do	Plans
Metrics	GET /api/v1/metrics only (Prometheus export)	Pro and up
Read-only	every GET of the API, no change	Max and up
Full	read and write: create, edit, delete (Terraform, CI)	Max and up

Give each tool the narrowest key it needs: a leaked Metrics key exposes the figures of your monitors, a leaked Full key lets someone delete them. A request beyond the key’s access returns 403 KEY_SCOPE.

Generate an API key

1. Go to Settings → API Keys.
2. Pick its Access (see above), give the key a name and, optionally, an expiry date (leave it empty for a key that never expires).
3. Click Generate new key.
4. Copy the key immediately — it’s shown once (oks_live_...).

Keys can be rotated (new value, same entry) or revoked from the same page, and an expiring key emails the organization’s owner 30, 14 and 7 days ahead. See Account security.

Authenticate a request

Send the key as a Bearer token on every request:

GET /api/v1/monitors HTTP/1.1
Host: api.okstatus.eu
Authorization: Bearer oks_live_xxxxxxxxxxxxxxxx

curl https://api.okstatus.eu/api/v1/monitors \
  -H "Authorization: Bearer oks_live_xxxxxxxxxxxxxxxx"

A missing or malformed key returns 401 UNAUTHORIZED. A key that’s valid but belongs to an org whose plan doesn’t include its access level (Max for Read-only and Full, Pro for Metrics) returns 403 FORBIDDEN. A request its access level doesn’t allow returns 403 KEY_SCOPE.

Rate limits

Requests are capped per organization: 5000 requests/hour, and about 150 per minute in a burst. Every response includes:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4998
X-RateLimit-Reset: 1700000000

Exceeding the limit returns 429 RATE_LIMITED.

Error format

Every error response — across every endpoint — uses the same shape:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor not found"
  }
}

What the API covers

Resource	Endpoints
Monitors	/monitors, /monitors/{id}, /monitors/{id}/checks, /monitors/{id}/uptime
Monitor channels	/monitors/{id}/alert-channels
Monitor groups	/monitor-groups, /monitor-groups/{id}
Private agents	/private-agents (read-only)
Incidents	/incidents, /incidents/{id}, /incidents/{id}/resolve
Maintenances	/maintenances, /maintenances/{id}
Status pages	/status-pages, /status-pages/{id}
Alert channels	/alert-channels, /alert-channels/{id}
Status snapshots	/status, /status/summary
Organization	/org

All of them sit under https://api.okstatus.eu/api/v1. Request and response schemas for every one are in the interactive reference.

Interactive reference

The full, always-up-to-date endpoint list (request/response schemas, try-it-out) lives at the interactive OpenAPI reference. The spec itself (/api/v1/openapi.json) is reachable without a key, so it can be fed into codegen tools.