Managing API keys

API keys are the credential your code uses to call the StatusOwl REST API. Each key belongs to one organization, carries a fixed set of scopes, and can be revoked or rotated at any time without affecting other keys.

Manage keys in the dashboard under Organization → API Keys.

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 — they're how the API distinguishes production from sandbox traffic. The first 18 characters (prefix + 8 hex of the secret) are stored as key_prefix and shown in the dashboard as the human-recognizable identifier of the key. The remaining 56 characters are the secret and only ever shown once at creation.

Creating a key

1. Click New API Key.
2. Give it a descriptive name (e.g. CI deployment, metrics scraper prod, staging webhook test).
3. Choose an environment:
   • Production — full access to your real organization's data (sowl_live_…).
   • Sandbox — keys reserved for testing. Same data scoping rules apply, but the prefix lets you keep production and test traffic distinguishable in your code, your logs, and your alerting (sowl_test_…).
4. Pick the scopes the key needs. Only scopes allowed by your current plan are selectable. Default to the smallest set that works — the create dialog selects all allowed scopes by default, but a CI script that only reads monitors should only get monitors:read.
5. Click Create key.

The plaintext key is shown once in a confirmation dialog. Copy it immediately and paste it into your secret store — the dashboard cannot show it again. If you close the dialog without copying, you'll need to rotate the key (or create a new one) to get a fresh value.

Rotating a key

Rotation generates a new plaintext for an existing key while keeping the key's name, scopes, environment, and ID stable. Use it when:

• You suspect the secret was leaked (committed to a repo, posted in a chat).
• You're following a periodic-rotation policy.
• You want to fence off a deployment without re-issuing scopes.

To rotate:

1. Open the ⋯ menu next to the key and click 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 with the new value before they retry, or expect 401 responses until they're redeployed.

Editing a key

You can edit a key's name and scopes at any time. Changes take effect on the very next request — there's no caching delay. The plaintext doesn't change on edit; if you want a new secret, use Rotate instead.

Scopes that aren't allowed by your current plan are hidden from the picker and silently dropped on save. If you downgrade your plan and an existing key has scopes that are no longer allowed, calls using the disallowed scope will start returning 403 — see Scopes for the full picture.

Revoking a key

Revocation is permanent. Open the ⋯ menu and click Revoke, then confirm. Once revoked:

• The next request from that key returns 401 Unauthorized (API key revoked).
• The key still appears in the dashboard for auditability, but cannot be un-revoked.
• The key counts against your historical key list but does not count toward your active key limit.

If you accidentally revoke a key, create a new one with the same scopes — there's no way to restore the old plaintext.

Active key limit

Your plan caps the number of active keys an organization can hold at once. The limit is shown at the top of the API Keys panel (e.g. "5 of 10 active keys"). Revoking a key frees up the slot immediately.

Per-key rate limit

Each key has a per-minute request budget (rate_limit_rpm). Default values follow the plan, and Enterprise customers can request a custom limit. The remaining budget is exposed on every successful response:

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

A 429 with X-RateLimit-Reset of <seconds> means you've spent the budget for this minute — back off and retry after the indicated interval.

IP allowlist (optional)

A key can be restricted to a list of source IPs. If the allowlist is set and the request comes from any other IP, the API responds with 403 Forbidden — IP not allowed for this API key.

The allowlist matches the client's apparent source IP after the request reaches our edge. If you're behind a NAT, allowlist the NAT's external address — not the internal box. If you're behind a CDN, the IP we see is the CDN edge; ask support if you need help wiring this up.

Expiry (optional)

A key can be created with an optional expiration timestamp. After that moment passes, the key starts returning 401 Unauthorized — API key expired. This is useful for time-boxed integrations: a contractor's read-only key for a one-month project, a CI deployment key tied to a release window, etc.

There is no automated rotation — when an expiry is reached, the key stops working and you'll need to create a replacement.

Last used and request count

The dashboard shows each key's last_used_at and historical request_count. These are updated asynchronously after each request — there's typically a few-second lag, and a small number of in-flight increments may be lost during process restarts. Treat them as analytics, not as a billing source.

Best practices

• One key per service. Don't share a single key across CI, staging, and production scrapers. Separate keys mean you can revoke one without breaking the others.
• Smallest possible scope. A read-only metrics scraper does not need monitors:write. The damage radius of a leaked key equals its scope set.
• Never commit a key. Use environment variables or a secret manager. GitHub's secret scanner catches sowl_live_* patterns and will alert you, but don't rely on that as your first line of defense.
• Rotate proactively. A quarterly rotation schedule for production keys is a healthy practice — it makes a real rotation (after a leak) feel like routine work instead of a fire drill.
• Use sandbox keys in tests. A sowl_test_ key is visually distinguishable in logs and pull-request diffs, which makes "wrong key in production" mistakes obvious before they're shipped.

Programmatic key management

There is currently no public API for creating or managing API keys — key lifecycle operations are dashboard-only. If you need automation, treat this as a one-time onboarding step in your provisioning process.