Authentication

Buzzabout supports two ways to authenticate:

• API keys — for REST clients and headless agents. One header, x-api-key. No expiry, no refresh.
• OAuth 2.1 — for interactive MCP clients (Claude Desktop, Claude on the web). The user signs in, the client stores a token. This is what you set up in the Claude install guide.

Use API keys for scripts, scheduled jobs, and headless agents. Use OAuth for human-in-the-loop chat clients.

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.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:

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.

Using API keys with MCP

The MCP server accepts the same x-api-key header as the REST API. Headless agents (your own integration, a server-side LLM pipeline) can authenticate this way without going through OAuth. See MCP / API key auth for the headless setup.

The one MCP tool that requires user-bound auth is buzzabout__ask — it impersonates a user against the AI assistant chat backend, so it needs an OAuth/JWT identity. API-key callers calling buzzabout__ask get a structured forbidden error. All ten other tools work fine with either auth method.

OAuth (MCP only)

Interactive MCP clients use OAuth 2.1 to obtain a user-scoped JWT. This is automatic when you install the Buzzabout MCP server in Claude Desktop or Claude on the web — the client handles the redirect, the authorisation code, and the token storage.

The OAuth surface is exposed at:

https://api.buzzabout.ai/mcp/oauth/...

You don't normally interact with it directly. If you're building your own MCP host, point your OAuth flow at:

https://api.buzzabout.ai/mcp/.well-known/oauth-authorization-server

and follow the discovered metadata. The setup matches the MCP OAuth 2.1 spec.

What's next

• Quickstart — first dataset, first mentions, with an API key.
• Connect Claude — install the MCP server in Claude Desktop with OAuth.
• Headless MCP / API key — wire MCP into a custom agent using x-api-key.