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

# Authentication

> How to authenticate requests to the Flozy External API.

Every request must include your API key. Keys are created and managed in **Settings → API Keys** (agency owners only).

## Sending your key

Send the key using **one** of these headers:

<CodeGroup>
  ```bash X-API-Key header theme={null}
  curl https://api.flozy.com/api/v1/external/leads \
    -H "X-API-Key: flz_live_your_key_here"
  ```

  ```bash Authorization header theme={null}
  curl https://api.flozy.com/api/v1/external/leads \
    -H "Authorization: Bearer flz_live_your_key_here"
  ```
</CodeGroup>

## Key format

Keys are prefixed with `flz_live_` followed by 64 hexadecimal characters:

```
flz_live_a3f8c2d1e4b5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0
```

<Warning>
  Keys are shown **only once** at creation. Store them securely — you cannot retrieve a key after closing the creation dialog.
</Warning>

## Scopes

Each key is issued with a specific set of scopes. Requests using a key that lacks the required scope return `403`.

| Scope                  | Description                                  |
| ---------------------- | -------------------------------------------- |
| `read:leads`           | List and read leads                          |
| `write:leads`          | Create, update leads, and upsert lead status |
| `delete:leads`         | Move leads to trash                          |
| `read:tasks`           | List and read tasks                          |
| `write:tasks`          | Create and update tasks                      |
| `delete:tasks`         | Move tasks to trash                          |
| `read:opportunities`   | List and read opportunities                  |
| `write:opportunities`  | Create and update opportunities              |
| `delete:opportunities` | Move opportunities to trash                  |
| `read:contacts`        | List and read lead contacts                  |
| `write:contacts`       | Create and update lead contacts              |
| `delete:contacts`      | Delete lead contacts                         |
| `read:pipelines`       | List pipelines and their stages              |
| `read:lead_statuses`   | List lead status definitions                 |
| `read:custom_fields`   | List custom field definitions                |

<Tip>
  Follow the principle of least privilege — only grant the scopes your integration actually needs.
</Tip>