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

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

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

Передавайте ключ в заголовке 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 в раннем доступе, ключи выдаются по запросу. Напишите в поддержку, какие права, охват, срок и IP-адреса нужны: мы подключим кабинет, выпустим ключ и поможем с первым запросом. Полный ключ передается один раз.

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

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

Чтение через 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.

#Срок действия и 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: начните список заново, а для ленты событий выполните восстановление.
Отзыв останавливает ключ сразу и навсегда. Отменить отзыв нельзя.
Выключить API можно для всего кабинета одной кнопкой в том же разделе. Пока доступ выключен, все ключи получают 403 api_disabled.

#Журнал

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

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

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

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