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.

Generate an API key

1. Go to Settings → API Keys.
2. 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 not on the Max plan returns 403 FORBIDDEN.

Rate limits

Requests are capped per organization: 1000 requests/hour. Every response includes:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
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
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.