API Reference

Authentication

API keys, scopes, and the headers every request needs.

Authentication

Kestrel uses bearer API keys. There are no OAuth flows and no session cookies.

curl https://api.kestrel.dev/v1/events \
  -H "Authorization: Bearer sk_live_4eC39HqLyjWDarjtT1zdp7dc"

Key types

Prefix	Name	Can read	Can publish	Safe in a browser
`pk_`	Publishable	Metadata only	No	Yes
`sk_`	Secret	Everything	Yes	No
`rk_`	Restricted	Per-scope	Per-scope	No

Test-mode keys carry an extra segment — sk_test_… — and operate on an isolated dataset. Events published with a test key are never delivered to production subscriptions.

A secret key grants full account access. If one leaks, roll it from Settings → API keys immediately; rolling takes effect within 30 seconds.

Restricted keys

Restricted keys carry an explicit scope list. Requesting an endpoint outside the scope returns 403 insufficient_scope.

scopespathstring[]required

Any of events:read, events:write, subscriptions:read, subscriptions:write, deliveries:read, deliveries:replay.

apiVersionpathstringdefault: 2026-06-01

Pins every response and every delivered payload to a version. See Migrating to v2.

expiresAtpathstring

RFC 3339 timestamp. Omit for a key that never expires. Maximum lifetime is 365 days.

Required headers

Authorizationheaderstringrequired

Bearer <key>. Basic auth is not supported.

Content-Typeheaderstringrequired

application/json on any request with a body.

Idempotency-Keyheaderstring

Optional on POST. A UUID you generate. Repeating a request with the same key inside 24 hours returns the original response instead of publishing twice.

Errors

Status	Code	Meaning
401	`missing_api_key`	No `Authorization` header.
401	`invalid_api_key`	Key is malformed, rolled, or expired.
403	`insufficient_scope`	Restricted key lacks the scope.
429	`rate_limited`	See Limits and quotas.

Errors share one envelope:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided has been rolled.",
    "requestId": "req_01HZXA7C4M"
  }
}

Log requestId on every failure. Support can trace a request end-to-end from it.