API keys

An API key lets your own tools, scripts, and AI agents pull your MentionFlow data without logging in by hand. Think a spreadsheet, a BI dashboard, or a Claude/MCP workflow. It is also what a client's Cloudflare Worker uses to send you crawler logs.

Each key carries a scope that limits exactly what it can do. So you can hand one out without handing over the keys to everything. You create and manage them on API keys.

What it does

A key ties a request to your workspace and to a scope. The scope decides what the request may do. Each key carries a name so you can tell them apart later.

How to use it

Create a key, name it after whatever will use it, and copy the value shown.

Keys are prefixed mf_. Every request passes the key in an Authorization: Bearer <key> header. See Authentication for the full auth model.

Authorization: Bearer mf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes

Use an ingest key wherever a key has to live somewhere exposed, such as a customer's Cloudflare Worker. A key stolen from there can submit crawler events and nothing else. It cannot read your data.

Project scoping

A key can also be restricted to specific projects (brands). By default a key sees every project in the workspace. Pick projects in the scope menu when you create the key, or change an existing key's scope from its row. The key then reads exactly those projects and nothing else, on every keyed surface: v1 API, MCP, and crawler ingest. A project outside the grant answers exactly like a project that doesn't exist.

This is the key-shaped version of per-project member access. Hand a client a key scoped to their own project and it cannot read your other clients' data. Scope changes are recorded in the workspace audit log. Widening a key's scope requires a verified email. Narrowing is always allowed. Keys minted automatically for a Cloudflare Worker are scoped to the connected project.

Expiry

A key can carry an expiry, chosen when you create it. The creation form defaults to 90 days, with 30 days, 1 year, and "No expiry" one click away. Past its expiry the key stops authenticating everywhere at once. Every request then answers an honest 401 naming the expiry date. A broken integration tells you exactly what happened instead of a bare "Unauthorized". Keys created before expiry existed have no expiry and behave exactly as they always did. So do keys minted automatically for Cloudflare Workers.

Rotation

Rotate, on the key's row, issues a replacement key with the same name, scope, project grant, and IP allowlist. If the old key had an expiry, the replacement gets the same lifetime measured from now. The replacement is shown once, like any new key.

The old key is not cut off. It keeps authenticating for 24 hours, then expires on its own. Swap the new value into your integration anywhere inside that window and nothing goes down. Rotation mints a key, so it carries the same verified-email gate as creating one. It is recorded in the audit log with both key prefixes.

IP allowlist

A key can be restricted to specific source addresses. "Any IP" on the key's row opens the allowlist editor: one IP or CIDR range per line, IPv4 or IPv6, up to 20 entries. With a non-empty allowlist, a request from any other address is refused with a 403, on every keyed surface. Clearing the list makes the key usable from anywhere again. That is a widening, so it re-runs the verified-email gate.

The check uses the client address our edge actually observed. The spoofable parts of the X-Forwarded-For chain are ignored. A request whose source can't be attributed at all is refused, never waved through. That includes requests that didn't come through the edge at all. An allowlisted key only authenticates on the normal production path, so header forgery against the origin can't impersonate a listed address. If your traffic leaves through NAT or a corporate proxy, allowlist that egress address.

How it's computed / enforced

Only owners and admins can create or revoke keys. It is the same guard used for member management. On creation, we generate the key, store only its SHA-256 hash and a short prefix, and return the plaintext once.

Creating a key also requires a verified email address for accounts created on or after 2026-07-11. A key reads workspace data, so minting one is an egress-gated action. Revoking a key is never gated. Accounts created before that date are grandfathered and unaffected.

Read access fails closed. One read guard sits in front of the v1 resource reads and the MCP server, and it accepts only an explicit full workspace key. An ingest key is refused with a 403. A key whose stored scope the current build does not recognize never authenticates at all. Ingest itself accepts both scopes, but only for posting crawler events. A workspace key can only ever see its own workspace's brands, so a key can never read across tenants.

Expiry and the IP allowlist are enforced at that same chokepoint, not per endpoint. Every keyed request passes through it. So they apply the same way to v1 reads, crawler ingest, and MCP, including any keyed surface added later. A request refused for expiry or source address is never recorded as the key's "last used" time.

Revoking a key does not delete its record. The row is kept, with name, prefix, and last-used time, so the audit trail stays intact. The key simply stops authenticating.

Limits

• Up to 10 active keys per workspace. Revoke one to make room. (Rotation briefly needs a free slot for the overlap window.)
• Creating, rotating, and revoking keys is owner/admin only.
• Creating or rotating a key requires a verified email (accounts created on or after 2026-07-11).
• ingest keys cannot read any workspace data.
• Expiry, when set at creation, is between 1 day and 2 years.
• IP allowlists take up to 20 entries (IPs or CIDR ranges).

Related

• Authentication: the full bearer-token auth model.
• Password and email verification: the verification gate on key creation.
• Crawler ingest: how an ingest-scoped key posts crawler events.
• Crawlers: what the ingested crawler data feeds.