Skip to content
StatusOwlDocs

Managing API keys

Create, rotate, revoke and constrain StatusOwl API keys from the dashboard.

Last updated

An API key is the credential your code presents to the read-only REST API. Each key belongs to one organization, carries a fixed set of scopes, and can be rotated or revoked without affecting any other key.

Manage keys in the dashboard under Organization → API Keys. API access is available on every plan.

Key format

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

The prefix plus the first few characters of the secret are stored as the key's displayed identifier. The rest is the secret, shown once at creation. StatusOwl stores only a SHA-256 hash of the whole key.

Creating a key

  1. Click New API Key.
  2. Name it after the thing that will use it — CI deployment, grafana scraper prod.
  3. Choose the environment: Production (sowl_live_…) or Sandbox (sowl_test_…). Both read the same organization data; the prefix exists so the wrong key is obvious in a log or a diff.
  4. Pick scopes. Grant the smallest set that works — the only endpoints that exist today need monitors:read.
  5. Click Create key.
The plaintext is shown once

Copy it straight into your secret store. StatusOwl keeps only a hash — if you lose the plaintext, nobody can recover it. Rotate the key to get a new value.

Rotating

Rotation issues a new plaintext while keeping the key's name, scopes, environment and identity. Rotate when a secret may have leaked, on a schedule, or when handing a deployment over.

  1. Open the ⋯ menu next to the key → Rotate.
  2. Confirm.
  3. Copy the new plaintext from the show-once dialog.

The old plaintext stops working immediately — there is no overlap window. Update your clients before they retry, or expect 401 until they redeploy.

Editing

Name and scopes can be edited any time; changes take effect on the next request. Editing does not change the plaintext — use Rotate for that.

Revoking

Revocation is permanent. The next request from that key returns 401 Unauthorized — API key revoked. The key stays visible in the dashboard for auditability but cannot be un-revoked and no longer counts against your active key limit.

Active key limit

Each organization can have 5 active keys at once, flat across every plan. The current count against the limit sits at the top of the API Keys panel. Revoking frees a slot immediately.

Per-key rate limit

Each key has a per-minute request budget. Where no override is set the budget is 600 requests per minute. The limit is per key, not per organization or per IP, so two keys in the same organization each get their own. Remaining budget is returned on every successful response:

text
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 60

See Rate limits & quotas.

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.

The allowlist matches the client's apparent source address as it reaches our edge. Behind NAT, allowlist the NAT's external address. Behind a CDN or proxy, the address we see is the proxy's.

Expiry

A key can carry an optional expiration timestamp, after which it returns 401 Unauthorized — API key expired. Useful for time-boxed access: a contractor's read-only key, a key scoped to a release window.

There is no automatic rotation at expiry. The key stops working and you create a replacement.

Last used and request count

The dashboard shows each key's last-used timestamp and a historical request count. Both are written asynchronously — expect a few seconds of lag, and treat them as analytics rather than as a billing record.

Practice worth adopting

  • One key per service. Then revoking one does not break the others.
  • Smallest scope that works. The blast radius of a leaked key is exactly its scope set.
  • Never commit a key. Environment variables or a secret manager. Nothing scans public repositories for StatusOwl keys on your behalf — if a key reaches a repo, rotate it.
  • Rotate on a schedule. A rotation you have done before is routine; a rotation you have never done, during an incident, is not.

No programmatic key management

Key lifecycle is dashboard-only. There is no API for creating, rotating or revoking keys, and none planned near-term. Treat key issuance as a one-time onboarding step in your provisioning process.

See also