> ## 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

> Limit what an API key can do by scoping it to specific API surfaces

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](#rotate-keys-instead-of-editing-them).

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

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

## 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](/guides/export-a-list) is how list data leaves the platform, and `campaigns` covers [knowledge hubs](/guides/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](/concepts/credits) |
| `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:

```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://fuseai.com/api/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>
  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.
</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.

**Narrowest scopes that work.** A pipeline that [builds lists from search](/guides/build-a-list-from-search) needs `search` and `lists` — nothing else. A tool that [uploads your contacts](/guides/upload-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:

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