Authentication

buzzabout authenticates REST and MCP requests with the same primitive: a long-lived API key sent in the x-api-key header. Interactive MCP clients (Claude Desktop, Claude.ai) can additionally exchange the OAuth flow for a JWT — 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_<random>. They're tied to one buzzabout account; every request the key makes is scoped to that account's resources.

Sending the key

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

curl https://api.buzzabout-staging.com/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-staging.com/v1/datasets?limit=1 \
  -H "x-api-key: $BUZZABOUT_KEY"

Rotation

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

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

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

Team-member semantics

Each API key carries two ids:

• account_id — the account that owns the key. Account-shared resources (datasets, mentions, audience datasets, audience profiles, tracking agents, pattern detections, custom parameters) are visible to every key on the same account, no matter which seat minted them.
• user_id — the acting seat. This matters for user-owned resources (chats). Each chat carries the user_id of the seat that created it, and only that seat can read it back through GET /v1/chats/{id}. Other team members (including the team owner) get a 404.

If you revoke a seat (remove the user from the team), all of that seat's API keys are deleted with them — no stale credentials linger. 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.