API keys

API keys authenticate programmatic access to the REST API. They’re scoped — a key meant for a read-only dashboard shouldn’t be able to delete monitors.

Manage keys in the WebUI at Settings → API keys.

Creating a key

Settings → API keys → New API key. Pick:

• Name — friendly label shown in audit logs and on the keys list.
• Scopes — one or more from the list below. Pick the smallest set that does the job.
• Optional expiry — auto-rotate by setting an expiration date.

On save, the full key is shown exactly once. Copy it now and paste it into your secret store. The API stores only a SHA-256 hash; we can’t recover the key for you later.

Keys are prefixed pw_live_.... The prefix is visible in the keys list so you can tell at a glance which key you’re looking at.

Using a key

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

curl -H "Authorization: Bearer pw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://api.pathwatch.app/api/v1/monitors

See the REST API reference for endpoints.

Scopes

Scope	Grants
monitors:read	List and inspect monitors + check results.
monitors:write	Create, update, delete, pause monitors.
alerts:read	List alert rules, channels, history.
alerts:write	Create, update, delete alert rules and channels.
incidents:read	List incidents and their timelines.
incidents:write	Create, update, resolve incidents.
status_pages:read	Inspect status page configuration.
status_pages:write	Create, update, delete status pages.
runners:read	List enrolled self-hosted runners.
runners:write	Enrol, rotate token, revoke runners.
org:admin	Implies every other scope. Use sparingly.

Scopes layer on top of the issuing user’s role permissions. An API key can only act on resources the underlying user is allowed to touch — a Viewer can mint a key with monitors:write scope, but the API still rejects writes because the user themselves can’t write. Keep scope and role aligned at issue time.

Rotation

Best practice is to rotate keys regularly:

1. Create a new key alongside the old one.
2. Deploy the new key to consumers.
3. Verify in the audit log that traffic has shifted to the new key.
4. Revoke the old key.

Setting an expiry date forces this rotation automatically. Expired keys return 401; the consumer’s logs will tell you which deploy forgot the rotation.

Revocation

Settings → API keys → Delete. Revocation is instant; the next request the key makes will 401. If you suspect a key has leaked, revoke first, investigate after.

IP allowlisting

Keys can optionally be locked to a list of CIDR blocks. Set them on the key from the settings page. A key from outside the allowlist 401s with "IP not allowed" — the request is logged but no further authentication is attempted.

Use IP allowlisting for keys used by static infrastructure (scheduled CI jobs, fixed-IP servers). Don’t allowlist a key that’s also used from developer laptops.

API keys vs session cookies

The WebUI uses a session cookie issued by Better Auth. API keys are exclusively for programmatic clients — never paste a pw_live_ key into the browser bar or store it in client-side code.

If you need browser-side access from your own application, proxy through your backend; the API key never leaves your server.