API authentication

The StatusOwl REST API uses bearer token authentication. Every request must present a valid API key in the Authorization header. Keys are scoped to one organization, carry an explicit set of scopes, and are managed from the dashboard — see Managing API keys for the full lifecycle.

Base URL

https://api.statusowl.net/v1

All examples on these pages assume that base URL. The API is HTTPS-only — plain HTTP requests are rejected at the edge.

Key format

sowl_live_<64 hex chars>    production key
sowl_test_<64 hex chars>    sandbox key

The sowl_live_ and sowl_test_ prefixes are part of the key — production and sandbox traffic are differentiated by prefix, which makes it obvious in your logs and pull-request diffs when a wrong-environment key is in play. The plaintext is shown once at creation; StatusOwl stores only a hash. See Managing API keys for creation, rotation, revocation, and best practices.

Making an authenticated request

Send the key as a Bearer token in the Authorization header:

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

Both Authorization: Bearer <key> and the bare token form (Authorization: <key>) are accepted, but the Bearer form is recommended — it matches the OAuth 2.0 convention most HTTP clients and proxies expect.

Content-Type: application/json is only required for endpoints that accept a request body. Read endpoints (the entire current v1 surface) ignore it.

Response envelope

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

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

Some error responses include extra fields (notably the structured 403 body described below) — the error field is always present.

Scopes

Each key carries a fixed set of scopes — granular permissions chosen at key creation time. A key with monitors:read can list and fetch monitors; the same key calling a write endpoint gets a 403. The available scopes and which scopes each plan can grant are documented on the Scopes & plan gating page.

When a key is missing the scope an endpoint requires:

HTTP/1.1 403 Forbidden
Content-Type: application/json

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

Use granted_scopes in your logs when triaging — it confirms exactly what the key has, without needing dashboard access.

Authentication errors

A 401 does not distinguish between "no header", "wrong key", and "revoked / expired key" — to keep the response useful for clients but not useful to attackers probing for valid prefixes. If you're debugging an unexpected 401, check the dashboard for the key's status (active, revoked, expired) before assuming a transport problem.

Rate-limit and quota headers

Every successful response carries the current per-key rate-limit headroom and the org's daily / monthly quota state:

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

X-RateLimit-Reset is the seconds until the per-minute window rolls over. On a 429, back off based on whichever envelope you crossed.

IP allowlist (optional)

A key can be restricted to a list of source IPs — see IP allowlist. Requests from any other IP get 403 Forbidden — IP not allowed for this API key, even if the scope check would otherwise pass.

Sandbox vs production

sowl_test_ keys are reserved for testing. They authenticate against the same organization data with the same scope rules as sowl_live_ keys — there is no separate sandbox dataset. The point of the prefix is to keep production and test traffic distinguishable in your code, your logs, and your alerting, so a wrong-environment key is obvious before it ships.

If you need a true isolated sandbox (separate data, fake monitor results), that is on the roadmap but not yet shipped.

What's next

• Managing API keys — create, rotate, revoke, scope, and constrain keys.
• Scopes & plan gating — full scope catalog and which scopes each plan can grant.
• Monitors API — the first shipped endpoint surface, with full request / response examples.