# Аутентификация и ключи

Каждый запрос подписывается ключом организации. Ключ определяет, что именно можно читать: права, пространства, кампании и тексты сообщений.

## Как передать ключ

Передавайте ключ в заголовке `Authorization` со схемой `Bearer`:

```http
GET /v1/me HTTP/1.1
Host: api.melioralab.io
Authorization: Bearer mel_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345
```

Ключ имеет вид `mel_live_` и 32 латинские буквы или цифры. Cookie кабинета и другие способы входа ключ не заменяют. Запрос без ключа или с неверным ключом получает 401 `invalid_api_key`. После 20 ответов 401 за 5 минут IP-адрес блокируется на 15 минут, поэтому не повторяйте запросы с неверным ключом в цикле.

Ключ в адресе запроса не принимается: параметр вроде `?api_key=...` дает 400 `unknown_parameter`. Если ключ однажды попал в адрес, журнал прокси или историю браузера, перевыпустите его.

## Получить доступ

API в раннем доступе, ключи выдаются по запросу. Напишите в [поддержку](https://docs.melioralab.io/support/), какие права, охват, срок и IP-адреса нужны: мы подключим кабинет, выпустим ключ и поможем с первым запросом. Полный ключ передается один раз.

Когда в кабинете открыт раздел API, ключами управляет **владелец или администратор**, у которого есть доступ ко всем пространствам и кампаниям кабинета. Остальные участники видят раздел только для просмотра.

1. Откройте **Настройки › Интеграции**, блок **API**.
2. Если доступ выключен, нажмите «Включить API».
3. Нажмите «Создать ключ», задайте имя, права, охват и при необходимости срок и IP-адреса.
4. Скопируйте ключ из окна «Ключ будет показан один раз».

Чтение через API доступно на тарифе Pro и выше. Если тариф ниже, подписка не действует или доступ кабинета приостановлен, запросы получают 403 с кодом причины: `api_not_available`, `subscription_inactive` или `organization_suspended`.

В кабинете может быть до 10 действующих ключей. В это число входят ключи в подготовке и старые ключи на время перекрытия при перевыпуске.

## Права

Права выбираются при создании ключа и меняются кнопкой «Изменить».

| Право | В кабинете | Что открывает |
|---|---|---|
| `campaigns:read` | Кампании | `GET /v1/campaigns`, `GET /v1/campaigns/{id}` |
| `leads:read` | Лиды | `GET /v1/leads`, `GET /v1/leads/{id}` |
| `messages:read` | Переписка | `GET /v1/leads/{id}/messages` и тексты в событиях |
| `events:read` | События | `GET /v1/events` |

`GET /v1/me` и `GET /v1/workspaces` доступны ключу с любым набором прав.

**Тексты сообщений** выдаются, только если у ключа есть право `messages:read` **и** включена галочка «Текст сообщений». Она выключена по умолчанию. Без нее `GET /v1/leads/{id}/messages` и запрос событий с `include_text=true` получают 403 `scope_required`.

## Охват

Охват ограничивает, какие данные видит ключ:

- **Пространства:** все существующие или выбранные, до 50.
- **Кампании:** все кампании выбранных пространств или выбранные, до 500.
- **Включать будущие:** при охвате «все» ключ увидит и пространства или кампании, созданные позже. Если галочку снять, охват фиксируется списком того, что есть на момент сохранения.

Объект вне охвата для ключа не существует: запрос к нему дает 404 `not_found`, так же как запрос к несуществующему объекту. Текущий охват ключа можно прочитать в поле `scope` ответа [`GET /v1/me`](https://docs.melioralab.io/reference/api-context/).

## Срок действия и IP-адреса

- **Срок действия** задается по UTC. После него ключ получает 401 `invalid_api_key`. Пустое поле означает ключ без срока. Срок виден в поле `expires_at` ответа `GET /v1/me`.
- **Разрешенные IP** задаются адресами или подсетями в формате CIDR, IPv4 или IPv6, до 50 записей. Запрос с другого адреса получает 403 `ip_not_allowed`. Пустое поле разрешает любые адреса.

## Подготовка нового ключа

Сразу после создания или перевыпуска ключ может быть в состоянии «Подготовка». В это время запросы получают 503 `integration_initializing` с заголовком `Retry-After`. Повторите запрос через указанное время. Подготовка длится не дольше 15 минут. Если за это время ключ не подготовился, его состояние станет «Не подготовлен», и запросы получат 401: выпустите ключ заново или напишите в поддержку.

## Перевыпуск

Кнопка «Перевыпустить» выдает новый секрет с теми же правами и охватом. Выберите срок перекрытия:

| Перекрытие | Что происходит со старым ключом |
|---|---|
| Без перекрытия | Отзывается сразу |
| Одни сутки | Работает еще 24 часа |
| Семь суток | Работает еще 7 дней |

Перекрытие позволяет обновить ключ на всех серверах без простоя. Курсоры, выданные старому ключу, продолжают работать с новым, если права и охват не менялись.

## Изменение и отзыв

- **Изменение** прав, охвата или галочки «Текст сообщений» вступает в силу сразу. Курсоры, выданные до изменения, после него дают 400 `cursor_mismatch`: начните список заново, а для ленты событий выполните [восстановление](https://docs.melioralab.io/events-polling/#vosstanovlenie).
- **Отзыв** останавливает ключ сразу и навсегда. Отменить отзыв нельзя.
- **Выключить API** можно для всего кабинета одной кнопкой в том же разделе. Пока доступ выключен, все ключи получают 403 `api_disabled`.

## Журнал

Кнопка «Журнал» у ключа показывает последние запросы за 14 суток: время, маршрут, статус, код ошибки и длительность. По `Request-Id` из журнала поддержка найдет нужный запрос.

## Хранение ключа

Ключ дает доступ к данным вашего кабинета. Обращайтесь с ним как с паролем:

- храните в менеджере секретов или переменных окружения сервера, не в репозитории;
- вызывайте API только с сервера: ключ не должен попадать в браузер или мобильное приложение;
- не пишите ключ в журналы; для поиска используйте его начало и последние 4 знака, которые видны в кабинете;
- выдавайте каждой интеграции свой ключ с минимальными правами и охватом;
- при подозрении на утечку сразу отзовите ключ или перевыпустите без перекрытия.