Scopes

Scopes restrict an API key to a subset of the API. You set them once, when the key is created in Settings → API Cockpit — they cannot be edited afterwards, so a key’s permissions are fixed for its lifetime. To change permissions, create a new key and rotate. The rules are simple:

A key with no scopes has full access to every endpoint.
A key with scopes is limited to exactly those surfaces.
Calling an endpoint outside your key’s scopes returns 403 INSUFFICIENT_SCOPE.

An unscoped key is a full-access key. That is convenient for exploration, but for anything you deploy, assign the narrowest scopes that work — a leaked lists-only key can’t send campaigns or spend search credits.

Available scopes

Scope	Grants access to
`lists`	`/business/lists`, `/business/exports`
`campaigns`	`/business/campaigns*`, `/business/knowledge-hubs`
`search`	`/business/prospects/search`, `/business/saved-searches`
`contacts`	`/business/contacts*`

Scopes map to surfaces, not individual endpoints: lists covers exports because exporting is how list data leaves the platform, and campaigns covers knowledge hubs because they exist to feed campaign copy.

Always accessible

Three read-only endpoints work with any valid key, regardless of scopes:

Endpoint	Returns
`GET /business/me`	The key owner’s identity
`GET /business/credits`	The current credit balance
`GET /business/prospects/filter-options`	Accepted prospect-search filter values

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:

curl https://api.tryfuse.ai/api/v1/business/me \
  -u "af_YOUR_KEY:"

{
  "user": {
    "id": "685409d3287883fbc17c0ced",
    "email": "ada@brightpay.com",
    "name": "Ada Nwosu"
  }
}

What a scope failure looks like

Calling a campaigns endpoint with a key scoped only to lists:

curl https://api.tryfuse.ai/api/v1/business/campaigns \
  -u "af_YOUR_KEY:"

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not have the scope required for this endpoint.",
    "param": null,
    "doc_url": "https://fuseai.com/api/errors/insufficient_scope",
    "request_id": "req_8f2a1c9d4e"
  }
}

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.

Unknown paths return 404 ENDPOINT_NOT_FOUND, never 403. So the two failure modes are distinguishable: a 403 means the endpoint exists and your key lacks the scope; a 404 means check your URL for typos.

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. Narrowest scopes that work. A pipeline that builds lists from search needs search and lists — nothing else. A tool that uploads your contacts needs contacts and lists.

Rotate keys instead of editing them

Because scopes are fixed at creation, rotation is the way to change a key’s permissions — and good hygiene on a schedule regardless:

Create the new key

In Settings → API Cockpit, create a key with the scopes you want. Copy it immediately — the full value is shown only once.

Deploy it

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

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.

Get started

Concepts

Guides

Available scopes

Always accessible

What a scope failure looks like

Best practices

Rotate keys instead of editing them

Next steps

Authentication

Errors

​Available scopes

​Always accessible

​What a scope failure looks like

​Best practices

​Rotate keys instead of editing them

​Next steps

Authentication

Errors

Available scopes

Always accessible

What a scope failure looks like

Best practices

Rotate keys instead of editing them

Next steps