Skip to main content
Scopes restrict an API key to a subset of the API. Every key holds a list of scopes, fixed when it is created, and each scope opens one surface of the API.
Keys created in Settings → API Cockpit carry every scope below, so they can call every endpoint. Choosing scopes for a key is not available in the app yet. Treat each key as a full-access key.
The rules are simple:
  • A key is limited to the surfaces its scopes name.
  • Calling an endpoint outside your key’s scopes returns 403 INSUFFICIENT_SCOPE.
A full-access key can spend credits, send campaigns and change data. Keep keys out of client-side code and source control, and revoke a key the moment it may have leaked. Even a narrower key can spend credits: lists covers list enrichment, smart columns and imports, all of which bill.

​
Available scopes

Scopes map to surfaces, not individual endpoints: lists covers folders, imports, and exports because they are how list data enters and leaves the platform, and campaigns covers templates, scheduled sends, and knowledge hubs because they exist to feed campaign sending. Keys hold the scopes that existed when they were created. When a new scope ships (like companies), existing keys are widened to include it as it rolls out, so a 403 INSUFFICIENT_SCOPE on a brand-new surface usually just means the roll-out has not reached your key yet.

​
Always accessible

Identity, quota, and reference reads work with any valid key, regardless of scopes — every id the API asks for, it also hands out: These are identity and quota reads. Every integration needs to verify its key works and monitor credit consumption, and none of that should require granting a broader scope. GET /business/me doubles as a health check:

​
What a scope failure looks like

Calling a campaigns endpoint with a key scoped only to lists:
The response uses the standard error envelope. A 403 here means the key itself is fine — retrying won’t help, and neither will a different endpoint under the same surface. Either use a key that carries the scope, or create one that does.
A path outside every scope’s prefixes returns 404 ENDPOINT_NOT_FOUND. A typo under a prefix your key lacks, such as /business/campaigns/typo on a key without campaigns, returns 403 instead, and an invalid key returns 401 before either.
If you’re getting 401 instead of 403, the problem is the key itself, not its scopes — see Authentication.

​
Best practices

One key per integration. Give your CRM sync, your enrichment pipeline, and your reporting job separate keys. When one leaks or misbehaves, you revoke it without taking the others down, and your usage is attributable per integration. Know what each integration needs. A pipeline that builds lists from search needs search and lists, and a tool that uploads your contacts needs contacts and lists. Keys from API Cockpit carry every scope today, so record what each integration calls.

​
Rotate keys

Keys never expire, so rotate them on a schedule:
1

Create the new key

In Settings → API Cockpit, create a new key. Copy it immediately — the full value is shown only once.
2

Deploy it

Update your integration to use the new key and confirm it works with GET /business/me.
3

Revoke the old key

Revoke the old key in API Cockpit. Revocation is immediate, so do this only after the new key is live everywhere.

​
Next steps

Authentication

How to create a key and send it with every request.

Errors

The error envelope and every code the API returns.