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

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»), щоб точно знати, який відкликати, коли щось зламалося, а не гадати за голою датою створення.