title: "API keys" description: "Create and manage API keys for accessing the BoxWatch API from scripts and automation." last_updated: "2026-05-24"

API keys

API keys let you call the BoxWatch API from scripts, automation, CI pipelines, and any other non-browser caller. Keys inherit your account's full permissions — treat them like passwords.

Create a key

1. Go to Dashboard → Account → API keys → New key.
2. Give it a descriptive name (e.g. "CI pipeline" or "Backup script").
3. Click Create.
4. Copy the key immediately. BoxWatch shows it once, then never again — only the prefix is retained for identification.

Keys look like:

bw_4f3a91e8c7d2b15a8e0f47c93b6d28a05c1f9e7b3a4d68f72c5e93a17b8d04e6f

The bw_ prefix is followed by 64 hex characters generated from crypto.randomBytes(32).

Use a key

Send it as a bearer token on the Authorization header:

curl -H "Authorization: Bearer bw_YOUR_KEY" \
  https://api.boxwatch.app/auth/me

API base URL is https://api.boxwatch.app — note there's no /api prefix. Endpoints are documented in the API reference.

What keys can do

A full-scope key inherits everything your account can do via the web dashboard:

• Read all servers, checks, processes, uptime checks, dashboards, status pages
• Create, update, and delete any of the above
• Manage webhook endpoints
• Read alert history
• View account info

It cannot:

• Change your password
• Set up or disable 2FA (those require an interactive session)
• Access another user's account

Per-scope keys (read-only, server-specific, etc.) aren't shipped yet. If you need a narrower credential for a specific use case, custom API endpoints give you a server-scoped read-only key with metric filters — that's the closest equivalent today.

Rotate a key

Revoke + create:

1. Dashboard → Account → API keys → Revoke the current key.
2. Click New key to create a fresh one.
3. Update consumers.

Rotation is manual; there's no scheduled rotation. We recommend rotating at least quarterly, or immediately if you suspect a leak.

Revoke a key

Dashboard → Account → API keys → Revoke. Effective immediately — the next request with that key returns 401 Unauthorized.

Security

• Never commit keys to git. Use environment variables, secrets managers, or your platform's secret store.
• Use server-side, not client-side. A key in browser JavaScript is a key in the world.
• Rotate after staff turnover. When someone with access to the key leaves, rotate.
• Scope by intent, not by key. Use custom endpoints for read-only consumers; reserve full-scope keys for trusted automation.

Rate limits

Rate limits are per account, not per key. The exact thresholds aren't published — under normal scripted use you won't hit them. If you're polling aggressively (sub-second), batch your reads or use custom API endpoints which are designed for high-frequency pulls.

If you start getting 429 Too Many Requests, slow down and retry with exponential backoff.

API

Create body:

{
  "name": "CI pipeline",
  "scope": "full"
}

Only scope: "full" is accepted today.

(API reference pages are coming soon — see /docs/api for the overview.)

See also

• API overview
• Custom API endpoints — scoped, read-only keys for metrics
• Two-factor auth