> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fuseai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> The API surfaces each key scope grants, the reads every key can make, and what a scope failure looks like

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.

<Note>
  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.
</Note>

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`.

<Warning>
  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.
</Warning>

## Available scopes

| Scope | Grants access to |
| - | - |
| `lists` | `/business/lists*`, `/business/exports*`, `/business/folders*`, `/business/imports*` |
| `campaigns` | `/business/campaigns*`, `/business/campaign-templates*`, `/business/scheduled-sends*`, `/business/knowledge-hubs*` |
| `search` | `/business/prospects/search*`, `/business/prospects/autocomplete`, `/business/saved-searches*` |
| `contacts` | `/business/contacts*` |
| `companies` | `/business/companies*` |
| `agents` | `/business/agents*` |
| `research` | `/business/research*` |
| `analytics` | `/business/analytics*` |
| `intent` | `/business/website-visitors`, `/business/website-tracking` |

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](/guides/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:

| Endpoint | Returns |
| - | - |
| `GET /business/me` | The key owner's identity |
| `GET /business/credits` | The current [credit balance](/concepts/credits) |
| `POST /business/credits/usage` | The spend ledger by product and day |
| `GET /business/prospects/filter-options` | Accepted prospect-search filter values |
| `GET /business/accounts?channel=` | Connected email / LinkedIn sending accounts |
| `GET /business/team/members` | Teammates (feeds `delegates`) |
| `GET /business/writing-styles` | Writing styles AI campaigns accept |
| `GET /business/integrations` | Which CRMs are connected |
| `GET /business/jobs/{jobId}` | A job's status by its 24-hex `jobId`, such as an export. Other `202`s have their own handle, see [Long-running work](/concepts/long-running-work) |

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:

```bash theme={null}
curl https://api.tryfuse.ai/api/v1/business/me \
  -u "af_YOUR_KEY:"
```

```json theme={null}
{
  "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`:

```bash theme={null}
curl https://api.tryfuse.ai/api/v1/business/campaigns \
  -u "af_YOUR_KEY:"
```

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

The response uses the standard [error envelope](/concepts/errors). 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.

<Note>
  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.
</Note>

If you're getting `401` instead of `403`, the problem is the key itself, not its scopes — see [Authentication](/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](/guides/build-a-list-from-search) needs `search` and `lists`, and a tool that [uploads your contacts](/guides/upload-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:

<Steps>
  <Step title="Create the new key">
    In **Settings → API Cockpit**, create a new key. Copy it immediately — the full value is shown only once.
  </Step>

  <Step title="Deploy it">
    Update your integration to use the new key and confirm it works with `GET /business/me`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    How to create a key and send it with every request.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/concepts/errors">
    The error envelope and every code the API returns.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.