Authentication

All /v1/* requests require a Bearer API key in the Authorization header.

Authorization: Bearer rec_live_aBcD1234EfGh5678...

Key format

• rec_live_<random>, production key, sends real events.
• rec_test_<random>, test key, same behavior, easier to distinguish.

Generate keys from the dashboard (one per environment). Keys are hashed (SHA-256) on the server, the full secret is shown only once at creation. If you lose it, revoke and generate a new one.

Scopes

Each key can be scoped to a subset of actions:

• events:write, ingest new events
• events:read, list, search, read
• exports:read, download CSV/JSON exports
• actors:delete, GDPR right-to-erasure
• embed:write, mint short-lived embed tokens

Embed tokens

For the internal <RecalledFeed /> admin widget, you mint a short-lived token server-side and pass it to the browser. The browser talks to /v1/embed/events with that token instead of the API key, so your API key never leaves the server. By default the token grants read access to the whole project (admin view); pass organization if you want to narrow a given widget instance to a single tenant.

const { token } = await client.embed.createToken({
  organization: "org_abc",
  ttlSeconds: 900,
});
// return `token` to the browser