Authentication

Bearer API keys, scoped to your workspace, shown once at creation and stored only as fingerprints.

Every /api/v1 call authenticates with an API key in the Authorization header:

curl https://webhookvault.dev/api/v1/me \
  -H "Authorization: Bearer wv_live_…"

Tools that can't set Authorization may send X-Api-Key: wv_live_… instead — the two are equivalent; Authorization is canonical.

Keys

Keys are created on the API keys page in the app (API access starts on the Solo plan; the number of active keys is a plan limit).

Named, always. A key is named for where it lives — CI pipeline · GitHub Actions — so you always know which one to rotate or revoke.
Shown once. The full key appears exactly once, at creation. After that only its fingerprint (SHA-256) is stored — nobody, including us, can read a key back. Lose it, revoke it, make a new one.
Workspace-scoped. A key acts as your workspace, not as a browser session: it sees every endpoint in the workspace, carries no cookies, and is authenticated fresh on every call.
Revocation is immediate and forever. A revoked key fails from that moment; it never comes back.

The key's identification prefix (wv_live_3fk9Qm2x) is safe to say out loud — in a support thread, a log line, a teammate conversation — without revealing the credential.

Verify a key

GET /api/v1/me is the cheapest possible call and tells you everything about the credential you're holding — who it is, what plan, what limits:

{
  "key": { "prefix": "wv_live_3fk9Qm2x", "name": "CI pipeline" },
  "workspace": { "name": "Acme" },
  "plan": { "key": "pro", "displayName": "Pro" },
  "limits": { "apiRatePerMinute": 600, "endpointsMax": 50, "retentionDays": 90 }
}

Failure modes

Status	`code`	Meaning
`401`	`unauthorized`	No key, an unknown key, or a revoked key.
`403`	`api_access_disabled`	The key is real, but its workspace's plan no longer includes API access.
`429`	`rate_limited`	The key's per-minute budget is spent — honor `Retry-After`.

Handling keys well

Keep keys in secret stores and environment variables, never in code or client-side JavaScript.
One key per system. When a pipeline is retired, its key is revoked and nothing else breaks.
The capture URL (…/hook/{id}) intentionally requires no authentication — its unguessable id is the token. Never put an API key in a sender's webhook configuration.

Where next?

Quickstart — put a key to work
Rate limits — budgets and backoff
GET /api/v1/me — the introspection call