Authentication

Every /v1 request authenticates with an API key sent as a bearer token:

Authorization: Bearer ww_live_<keyId>.<secret>

The scheme word is matched case-insensitively; the key itself is not. There is no other way in — no session cookie, no query parameter, no basic auth.

A key carries its own organisation and its own role, so no /v1 path contains an organisation id. GET /v1/me answers with the org and role the presented key resolves to, which makes it the cheapest way to confirm a key works.

Creating a key

Keys are created in the dashboard, at Settings → API keys, and nowhere else. The endpoint behind that screen is POST /orgs/:orgId/api-keys; it is authenticated by your session, not by a key, and it requires the api_key:manage permission — held by Owner and Admin only. An Editor or a Viewer is refused with 403.

/v1 cannot mint, list or revoke keys. That is deliberate: a leaked key can drive the API, but it can never grant itself a successor. Key lifecycle is a human, session-gated action.

When you create a key you choose:

• a name, so you can tell keys apart when you revoke one;
• a role — Admin, Editor or Viewer — which bounds what the key may do on /v1, independently of the role of the person who created it;
• an optional expiry. Without one the key lives until it is revoked.

Creating a key on a plan without API access is refused with 403 feature_gated, the same answer /v1 itself gives — see Errors and rate limits.

The secret is shown exactly once

The response to the create call is the only time the full key is ever readable. Only a SHA-256 hash of the secret is stored, so nothing — not the dashboard, not support, not the database — can show it to you again. The key list is masked.

Copy it into your secret store at creation time. If you lose it, revoke the key and create another.

Using a key

curl -sS https://api.wirewatch.io/v1/me \
  -H "Authorization: Bearer $WIREWATCH_API_KEY"

An absent, malformed, unknown, revoked or expired key all answer the same 401 — the API never distinguishes them, because doing so tells an attacker which of their guesses was closer.

Revocation and expiry are checked on every request against the database, with no cache: a revoked key stops working immediately.

Revoking a key

DELETE /orgs/:orgId/api-keys/:id, again from the dashboard and again gated by api_key:manage. Revocation is immediate and cannot be undone. A key id that does not belong to your org answers 404, never 403, so the API never confirms that someone else’s key exists.

Roles

A key’s role is fixed when the key is created and bounds every request it makes:

Role	On /v1
Admin	read and write monitors
Editor	read and write monitors
Viewer	read only — a write answers 403 forbidden

A key can never exceed its own role, and no role lets a key escape its organisation.