Гайд - Платформа

API-ключи

API-ключ - это учётные данные вашего аккаунта для Leadgram API V2. Управляются они в настройках: здесь вы создаёте ключ, даёте ему имя и отзываете, когда нужно. Разберём, что умеет ключ, как его создать, как он привязан к аккаунту, какой формат запроса под него рассчитан, и как его ротировать или отозвать.

Зачем нужны API-ключи

API-ключ позволяет внешнему инструменту или скрипту обращаться к Leadgram API от вашего имени, не передавая ему логин или сессионную куку. Это механизм для server-to-server интеграций - например, Keitaro забирает данные, или скрипт отправляет события - а не для использования в браузере.

Создание ключа

  1. Откройте Настройки → API-ключи.
  2. Дайте ключу название, по которому узнаете его позже, например «Keitaro» или «скрипт отчётов» - это единственное поле в форме.
  3. Нажмите Создать ключ. Секрет показывается ровно один раз, сразу после создания, в блоке для копирования - скопируйте его сейчас же. Ни таблица ключей, ни какой-либо запрос больше не покажут полное значение - сохраняются только название и дата создания.
Панель API-ключей с диалогом создания ключаПанель API-ключей с диалогом создания ключа

Скоуп и привязка к организации

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

Использование ключа в server-to-server запросах

Ключ передаётся в заголовке запроса x-api-key - именно под это имя заголовка рассчитан Leadgram API:

curl https://leadgram.org/api/<endpoint> \
  -H "x-api-key: YOUR_API_KEY"

Аутентификация запросов по API-ключу пока не включена на эндпоинтах. Управление ключами (создание, имя, отзыв) уже работает, а аутентификация запросов - в разработке. Это формат запроса, которым вы воспользуетесь, когда она заработает, а не рабочий путь интеграции прямо сейчас.

Подставьте нужный эндпоинт вашей интеграции, когда аутентификация запросов станет доступна.

Ротация и отзыв

Механизма «перегенерировать на месте» нет - секрет ключа фиксирован на всё время его жизни. Чтобы ротировать ключ: сначала создайте новый, подставьте его в интеграцию, убедитесь, что всё работает, и только потом отзовите старый ключ в таблице, чтобы ничего не осталось работать на нём. Отзыв происходит мгновенно - нажмите Отозвать в строке ключа, и он сразу перестаёт работать, без периода на переезд, поэтому сначала переключайтесь, потом отзывайте, а не наоборот.

Частые грабли

  • Секрет показывается один раз, при создании. Закрыли диалог, не скопировав, - он потерян навсегда: отзывайте ключ и создавайте новый.
  • Ключ несёт полный доступ вашего аккаунта - не вставляйте его в чат поддержки, публичный репозиторий или общий скрипт, а если утёк - ротируйте.
  • У отзыва нет отмены и нет задержки: любая интеграция, которая всё ещё использует старый ключ, сразу начинает падать.
  • Называйте ключи по тому, куда они подключены (например «Keitaro prod»), чтобы точно знать, какой отзывать, когда что-то сломалось, а не гадать по голой дате создания.