API keys.
API keys authenticate the CiteHawk REST API and the MCP server. Each key belongs to one workspace and grants access to that workspace’s data only.
Creating a key
In the app, open your workspace Settings and find the API Keys card on the General tab. Only workspace admins can see it, so if the card is missing, check your role.
Give the key a name you will recognize later, choose its scopes and expiry, and create it. Keys look like this:
chk_a1b2c3d4e5f6…The full key is shown once, at creation. CiteHawk stores only a hash of it, so it cannot be shown again and cannot be recovered. Copy it somewhere safe before you leave the page. Afterwards the card shows only the first few characters, enough to tell your keys apart.
Using a key
Pass the key as a Bearer token on every request:
Authorization: Bearer YOUR_API_KEYA missing or malformed header returns 401 Unauthorized. So does a key that has been revoked or has expired. A valid key that lacks the scope for the endpoint returns 403 Forbidden, naming the scope it needed.
Requests are rate limited per key. See the REST API reference for the endpoints, and the API quickstart for a first call.
Scopes
Scopes narrow what a key can do. The available scopes are:
| Scope | What it opens |
|---|---|
read:brands | Read the brands tracked in the workspace. |
read:metrics | Read the daily metrics timeseries and the latest KPIs. |
read:responses | Read the collected AI answers themselves. |
read:scores | Read the Visibility and Brand Health scores and their history. |
write:prospect-scans | Start white-label prospect scans and read their results. A write scope, and gated to the Agency plan. |
Selecting no scopes gives full read access. A key with nothing checked can call every read endpoint, which is the convenient default for a key you control. Checking specific read scopes narrows the key to exactly those.
Write scopes are never granted by default. A write scope applies only when you check it explicitly, so an unscoped key can read everything and write nothing.
Scopes and MCP
The MCP server accepts unscoped keys only. Its tools read across scores, metrics, rankings, source gaps, recommendations, and evidence, which is broader than any single REST scope. Honoring a scoped key there would quietly hand it access its creator had deliberately withheld, so CiteHawk rejects it instead.
The rejection arrives as an ordinary authorization failure with no specific explanation, which makes it easy to misdiagnose. If a key works against the REST API but an MCP client will not connect, check whether the key has scopes selected. Use an unscoped key, or connect over OAuth, which avoids keys altogether.
Expiry
A key can be set to never expire, or to expire after 30 days, 90 days, or one year. Expired keys stop authenticating and are marked as expired in the settings card rather than disappearing, so you can see what lapsed.
Prefer an expiry for anything you hand to a third party or paste into a service you do not operate. An expiry is a revocation you do not have to remember to perform.
Revoking a key
Delete a key from the same settings card. Revocation takes effect immediately and cannot be undone; issue a new key rather than trying to restore an old one.
Connections made over OAuth are not API keys and are revoked separately, under Connected apps in your account settings.
Handling keys safely
- Treat a key as a password. It grants read access to your workspace’s visibility data to anyone holding it.
- Keep keys out of client-side code and version control. A key in a browser bundle or a public repository is a key you have published.
- Use one key per integration. Separate keys mean you can revoke one thing without breaking everything else.
- Scope down where you can. A script that reads scores does not need to read every collected answer.
