Skip to content
StatusOwlDocs

Authentication

Authenticate requests to the StatusOwl REST API with a bearer API key.

Last updated

The StatusOwl REST API uses bearer-token authentication. Every request presents an API key in the Authorization header. Keys belong to one organization, carry an explicit set of scopes, and are managed from the dashboard.

The API is read-only

Two endpoints exist: list monitors and retrieve a monitor. There are no write endpoints, no incident or status-page endpoints, and no outbound webhooks. See Monitors API for the full surface, and the roadmap for what is planned.

The API is available on every plan.

Base URL

text
https://api.statusowl.net/v1

HTTPS only. A machine-readable OpenAPI document is served by the same service.

Key format

text
sowl_live_<hex>    production key
sowl_test_<hex>    sandbox key

The prefix is part of the key. The plaintext is shown once at creation; StatusOwl stores only a SHA-256 hash. See Managing API keys.

Making a request

bash
curl https://api.statusowl.net/v1/monitors \
  -H "Authorization: Bearer sowl_live_xxxxxxxxxxxxxxxxxxxx"

Both Authorization: Bearer <key> and the bare Authorization: <key> form are accepted. Prefer Bearer — it is what clients and proxies expect.

Content-Type is irrelevant on the current surface, since nothing takes a request body.

Response envelope

json
// Success
{ "data": { ... } }

// Error
{ "error": "Descriptive error message" }

Collection endpoints add a top-level pagination object alongside data. Some errors carry extra structured fields; error is always present. See Errors.

Authentication errors

StatusWhen
401 UnauthorizedMissing header, malformed key, unknown key, revoked, or expired.
403 ForbiddenValid key, but missing the required scope, the source IP is not on the key's allowlist, or the organization is not active.
429 Too Many RequestsPer-key rate limit or per-organization quota exceeded. See Rate limits.

A 401 does not distinguish "no header" from "wrong key" from "revoked" — the response is the same either way so a prefix cannot be probed. When debugging an unexpected 401, check the key's status in the dashboard before suspecting the transport.

A missing scope returns a structured body naming what was needed and what the key has:

json
{
  "error": "Missing required scope",
  "required_scope": "monitors:read",
  "granted_scopes": ["account:read"]
}

Rate-limit and quota headers

Every successful response carries the current headroom:

text
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 60
X-Quota-Daily-Limit: 100000
X-Quota-Daily-Remaining: 99873
X-Quota-Monthly-Limit: 3000000
X-Quota-Monthly-Remaining: 2987112

The numbers above are illustrative — the values on your own responses are the authoritative ones. X-RateLimit-Reset is seconds until the per-minute window rolls over.

IP allowlist

A key can be restricted to a set of source IPs. Requests from anywhere else get 403 Forbidden — IP not allowed for this API key, even when the scope check would have passed. See IP allowlist.

Sandbox keys

sowl_test_ keys authenticate against the same organization data with the same scope rules as live keys. There is no separate sandbox dataset and no synthetic monitor results. The prefix exists so a wrong-environment key is obvious in a log line or a pull-request diff before it reaches production.

A genuinely isolated sandbox does not exist.

What's next