Создание и хранение API-ключа

Ключ — это пароль вашей интеграции. По нему определяется рабочая область и то, что интеграции разрешено делать.

Создание

Раздел интеграций → создать ключ. Укажите название (чтобы потом понимать, чей он) и отметьте нужные права.

Ключ показывается один раз. Скопируйте его сразу и сохраните в надёжном месте: восстановить значение мы не сможем — в базе хранится только отпечаток. Потеряли — создайте новый и отзовите старый.

Права

Выдаются по областям и раздельно на чтение и запись:

• обращения — читать / создавать и изменять;
• контакты — читать / создавать и изменять;
• материалы ассистента — читать / добавлять и искать.

Давайте только то, что нужно. Интеграции, которая заводит заявки, не нужно право читать контакты — а если ключ утечёт, лишние права станут проблемой.

Как хранить

• На сервере, в переменных окружения или хранилище секретов.
• Не в коде фронтенда, мобильного приложения и не в репозитории: всё это видно посторонним.
• Для разных интеграций — разные ключи: тогда при компрометации отзывается один, а не всё сразу.

Отзыв

Ключ отзывается в том же разделе, действует немедленно. Отзывайте, если:

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

Отозванный ключ восстановить нельзя — создавайте новый.

Проверка связи

После создания сделайте тестовый запрос к проверочному методу: он ничего не меняет и показывает, что ключ принят.

Если ответ «не авторизован» — проверьте, что ключ передаётся в заголовке целиком и не обрезан при копировании.

Если «недостаточно прав» — ключу не выдана нужная область: права правятся созданием нового ключа.

Ограничения по частоте

Запросы ограничены по числу в минуту, отдельно на чтение и запись. Массовые выгрузки делайте порциями, а не одним потоком.

Что дальше

Создание обращений через API. Вебхуки: получаем события у себя.