Authentication

API keys for REST + MCP — minting, sending, rotating, and what team-member semantics look like.

buzzabout authenticates REST and MCP requests with the same primitive: a long-lived API key sent in the x-api-key header. Interactive assistants (Claude) can additionally exchange an OAuth flow for a JWT on the MCP surface — see MCP / Authentication for that path. The REST API is api-key only.

API keys

API keys live under Settings → API keys in the web app. Click New key, name it, copy the value — it's shown once.

Keys look like bz_live_<32 hex> (for example, bz_live_abcdef1234567890abcdef1234567890). They're tied to one buzzabout account; every request the key makes is scoped to that account's resources.

The raw key is never stored on the server

buzzabout stores only the SHA-256 digest of your key, not the key itself. Once you close the New key dialog the raw value cannot be retrieved — not by you, not by buzzabout support, not even with database access. If you lose it, revoke the lost key and mint a new one. Treat the dialog as a one-shot prompt: copy the value into your secret manager before dismissing it.

Sending the key

GET /v1/datasets HTTP/1.1
Host: api.buzzabout.ai
x-api-key: bz_live_abcdef1234567890abcdef1234567890

cURL

curl "https://api.buzzabout.ai/v1/datasets" \
  -H "x-api-key: $BUZZABOUT_KEY"

Verifying a key

Hit GET /v1/datasets with limit=1. A 200 means the key is valid. A 401 means it's missing or revoked.

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://api.buzzabout.ai/v1/datasets?limit=1" \
  -H "x-api-key: $BUZZABOUT_KEY"

Rotation

There's no built-in expiration. Rotate by:

Creating a new key under Settings → API keys.
Updating your environment / secret store.
Revoking the old key.

Revoked keys return 401 immediately on the next call — there's no grace period.

Team-member semantics

Most resources (datasets, mentions, audience datasets, audience profiles, tracking agents, pattern detections, custom parameters) are account-shared — visible to every key on the same account regardless of which seat minted them.

The one exception: chats are per-seat. A chat is only readable by the seat that created it; other team members get a 404 from GET /v1/chats/{id}. If you revoke a seat, their keys are deleted with them — plan to rotate any service-account-style integrations through a seat you keep.

Using API keys with MCP

The MCP server accepts the same x-api-key header as the REST API. Headless agents — your own SDK-built integration, a server-side LLM pipeline — authenticate this way without going through OAuth.

See MCP / Authentication for the headless wiring and the OAuth-for-interactive-hosts path.

Next steps

Quickstart — first dataset, first mentions.
MCP authentication — x-api-key and OAuth/JWT paths for the MCP server.
Pricing — what each authenticated call costs.