Authentication

The v1 API and the MCP server sign in one way: a workspace API key sent as a bearer token.

The header

Send your key in the Authorization header on every request, with the Bearer scheme:

Authorization: Bearer mf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

There is no X-API-Key header and no query-string key. The bearer header is the only form we accept.

Key format

Workspace keys start with mf_ and then 40 hexadecimal characters. You see a key in plaintext once, when you create it. We store only a SHA-256 hash, so we cannot show it again. Save it right away. Keys are created and managed on API keys.

Key scopes

A workspace key has one of two scopes. You pick it when you create the key:

The ingest scope is narrow on purpose. If such a key leaks from a customer's edge worker, it can ship logs but cannot read any workspace data. Read surfaces fail closed: an ingest scope, or any we do not recognise, is rejected on every read.

Scoping and privacy

Every response comes from the brands your key's workspace owns, and nothing else. Ask for a brand in another workspace and you get the same "unknown brand" response as a brand id that does not exist. The API never reveals whether another workspace's id is real.

A key can also carry a project grant (see API keys). It then reads exactly the granted projects on every keyed surface: v1 reads, MCP tools, crawler ingest. An ungranted project answers the same as one that does not exist. brands and list_brands list only the grant, and when you omit brand the default project resolves inside it. Grants are opt-in, and a key without one behaves exactly as before.

Errors you'll see

Full error shapes are in Errors.

Related

• API keys: creating, scoping, and revoking keys.
• Conventions: scales, windows, and null handling.
• Crawler ingest: the one endpoint an ingest key can reach.