API keys and agency access

The Convultra API and MCP server are in Beta. Secret sk_ keys are created under Settings → Developer and are the credential for the REST API and for MCP clients that authenticate with a static header. This page covers how keys are made, who owns them, what they can see, and how agency keys reach every client.

Creating a key

1. Go to Settings → Developer → Create key.
2. Give it a name that says what it is for, such as “Warehouse sync” or “Cursor, Dan”.
3. Tick the scopes the integration needs. Scopes only narrow access. See API scopes.
4. Choose which projects it may read, or all of them.
5. Pick an expiry: 30, 90 or 365 days, or never. 90 is the default.

The key is sk_ followed by 40 characters and is shown once. Only a SHA-256 hash is stored, so nobody, including Convultra support, can recover it. If you lose it, revoke it and make another.

Confirm it works with a call that needs no scope:

curl -s https://data.convultra.com/v1/me \
  -H "Authorization: Bearer sk_your_key_here" | jq '.data.name, .data.scopes, .data.projects[].domain'

How many keys you can have

Rate limits per plan are in the API overview.

Revoking a key

Revoke from the Developer tab. The key stops working immediately, and the next request with it returns 401 invalid_token. Revoke and replace a key when it may have leaked, when the integration it served is retired, or when its scopes need to change, since scopes on an existing key are fixed at creation.

A key belongs to an account or an agency, never to a person

An sk_ key created by a team member keeps working after that person leaves, and it cannot be revoked by accident along with their seat. It also means a key can never be minted with more reach than its owner has.

Superadmins are not a back door into key creation. A superadmin session sees every project in the dashboard, but cannot mint a key that does, because a key is owned by an account or an agency and never by a person.

The visibility rule

One rule decides who can see a project, and it is the same rule the dashboard applies:

1. a superadmin,
2. the account that owns it,
3. a team member of that account or of that specific project,
4. an agency with an active client relationship to the owning account.

On top of that rule, two narrowings apply, and both only ever subtract:

• The credential’s own project list. A key or an OAuth grant can be restricted to named projects, and then it sees only those.
• The member’s own scope. An agency member restricted to certain clients sees only those clients through an OAuth connection, even where the agency as a whole reaches more.

A project the credential cannot reach returns 404, never 403, so the API never confirms which project ids exist. GET /me lists what a credential can reach.

Agency keys

Agency keys are available on the Agency and Enterprise plans. Such a key belongs to the agency and reaches every account the agency actively manages, which is the point: one key, forty clients, one warehouse sync or one MCP connection. There is no person behind it, so no member’s client scope narrows it; the agency’s active client list is the boundary.

Ending a client relationship removes that client’s projects from the key immediately. On plans without the entitlement, creating an agency key is refused with 403 plan_required.

list_projects on an agency key returns every client’s projects with tracking health, currency and timezone, so a sync can iterate the portfolio without keeping its own list. See Agency dashboard overview.

Viewers are read-only

A Viewer can read everything their role allows and write nothing; an attempted write is 403 read_only_role. retry_delivery is the only write in this version, so in practice this is the one place a Viewer meets a wall. This applies to OAuth connections, where a person’s role is known. See Inviting your team.

proj_ keys are not API keys

The proj_... key under Settings → Tracking → Install is the public tracking key. It is rendered into every visitor’s browser and is write-only: it records events and cannot read anything. Using it as a bearer token returns 401 invalid_token with a message saying so. It is, however, a valid way to name a project in a path. See the API overview.

Keeping keys safe

• Never put a key in a URL. The API refuses token, api_key, apiKey, access_token and key query parameters before authentication.
• Never ship an sk_ key in a browser. Use it from a server, a CI job, or an editor config on your own machine.
• Store it in a secrets manager or environment variable, not in source control.
• Prefer short expiries for keys that live in files, such as a Cursor config.
• Quote the X-Request-Id header, never the key, when contacting support@convultra.com.