API keys

An admin makes keys under Settings, API & webhooks. The API comes with Growth and the plans above it. A key is sent as a bearer token:

curl -H "Authorization: Bearer ca_…" https://app.vercatus.com/api/org/sites

The secret is shown once, when the key is made; Vercatus keeps only its hash. Keys take no seat, and no key reaches admin or owner settings (members, billing, security, other keys): those need a signed-in member.

Scopes

Scope	What the key may do
read	Read what a viewer reads: sites, topics, Answer Share, competitors, plays, results, runs and their findings, reports
write	Also change what an analyst changes: topics and competitors, plays (status, owner, checks, hand-offs), experiments, runs, prompts, finding statuses. A write key also reads
export	Only the exports and report downloads (/api/export/*, a run’s report, the board brief, the quarterly review). The scope for Looker Studio and other BI tools

A request the scopes do not cover is refused with 403 and a sentence that says which scope it needs. The API reference and the OpenAPI document (GET /api/openapi.json, the x-vercatus-key-scopes of each operation) list the scope every route needs.

Expiry

A key expires a year after it is made unless you choose otherwise: 30 days, 90 days, a year or two years. An Enterprise workspace may also make a key without an expiry. A key made before keys expired keeps working until it is revoked; rotate it to give it an expiry. The list marks a key that expires within 14 days, and a request with an expired key is refused with 401.

Sites

A key can be limited to some sites of the workspace. It then reads and changes only those sites: a request for another site’s data is refused with 403, and so is a view that spans the whole workspace (the portfolio, the board brief, Home). Lists that take ?siteId= (findings, runs, prompts) need one of the key’s sites named; the site lists, the workspace’s top plays and results, and the exports return only the key’s sites. An agency gives each client’s tools a key limited to that client’s site.

Addresses

A key can be limited to IP addresses or CIDR ranges (IPv4 and IPv6, up to 50), such as your CI runners’ or your data warehouse’s egress. A request from anywhere else is refused with 403.

Rotation

Rotate makes a replacement with the same name, scopes, sites and addresses and a new expiry, and leaves the old key working for a grace period you choose (none, an hour, a day, three days or a week). Deploy the new secret; the old key stops by itself at the end of the grace period. POST /api/org/api-keys/:id/rotate with { graceHours, expiresInDays } does the same from a script run by an admin’s session.

Rate limit

300 requests a minute per key. Every answer carries x-ratelimit-limit and x-ratelimit-remaining; past the limit the answer is 429 with retry-after in seconds.

Audit

Making, changing, rotating and revoking a key are in the audit log with the member who did it. What a key changes is recorded as that key (api key ca_abc123 (name)). The list shows who made each key and when it was last used, to the minute.