Кожен запит до Telm API автентифікується API-ключем, що починається з tk_live_ — ніколи логіном панелі керування. Створіть ключ у своєму акаунті, надішліть його в заголовку Authorization як Bearer-токен, і він діє від імені вашого акаунта на групах, де ви адмін. Якщо ключ витік, відкличте його в панелі керування та випустіть новий.
1Як працюють API-ключі
Telm REST API не використовує сесію вашого браузера. Натомість кожен запит несе API-ключ — довгий секретний рядок, що починається з префікса tk_live_, за яким ідуть випадкові символи. Ключ ідентифікує ваш акаунт та авторизує виклик.
Ви генеруєте ключі у своєму акаунті й можете тримати кілька одразу (наприклад, по одному на скрипт чи сервіс). Повний секрет показується лише раз, у момент створення; згодом панель керування перелічує ключ за його коротким префіксом (tk_live_ плюс перші символи), щоб ви могли його впізнати, а повне значення після цього ніколи не зберігається.
- Ключ виглядає як tk_live_, за яким іде довгий випадковий рядок.
- Ключі створюються та керуються в панелі керування.
- Повний секрет показується лише раз — скопіюйте його негайно та зберігайте в надійному місці.
- Ставтеся до ключа як до пароля: будь-хто, хто його має, може викликати API як ви.
2Надсилання ключа з кожним запитом
Передавайте ключ у заголовку Authorization за схемою Bearer. Значення заголовка — це слово Bearer, пробіл, а тоді ваш ключ — наприклад, Authorization: Bearer tk_live_your_key_here.
Для клієнтів, які не можуть зручно встановити заголовок Authorization, API також приймає ключ у заголовку X-API-Key. Якщо присутні обидва, заголовок Authorization має перевагу. Запити через щось інше, ніж HTTPS, у продакшені не приймаються.
- Бажано: надсилайте Authorization: Bearer tk_live_...
- Альтернатива: надішліть ключ у заголовку X-API-Key.
- Базовий URL кожного виклику — api.telm.com/api/public/v1.
- Див. повний перелік ендпоінтів та схеми на сторінці для розробників.
3До чого має доступ ключ
Ключ діє строго від імені вашого акаунта. Він може лише читати чи змінювати групи, де ваш акаунт є адміном — запит, націлений на будь-яку іншу групу, повертає 404, тож API ніколи не розкриває, що група, якою ви не можете керувати, взагалі існує.
Доступ також залежить від тарифу цільової групи. Ендпоінт перевірки спаму відкритий для кожного тарифу в межах денної квоти, тоді як повний API (правила, налаштування, білий список, журнал, аналітика, пакетні перевірки та вебхуки) доступний на тарифі Pro чи вище на залученій групі.
- Ключ може торкатися лише груп, де ви адмін.
- Запити до груп, якими ви не керуєте, повертають 404, а не 403.
- Денна квота спільна для всіх ваших ключів, рахується на акаунт.
4Відкликання та ротація ключів
Якщо ключ розкрито — закомічено в репозиторій, вставлено в чат чи витекло будь-яким іншим шляхом — відкличте його негайно зі своєї панелі керування. Відкликання набуває чинності одразу: відкликаний ключ перестає працювати за секунди, а не з якоюсь затримкою.
Оскільки денна квота спільна на акаунт, відкликання одного ключа не скидає ваш лічильник використання. Регулярна ротація ключів — хороша гігієна: створіть новий ключ, розгорніть його у свій сервіс, підтвердіть, що він працює, а тоді відкличте старий, щоб не було простою.
- Відкличте ключ зі своєї панелі керування; він перестає працювати майже одразу.
- Спершу створіть заміну, розгорніть її, а тоді відкличте старий ключ для ротації без простою.
- Відкликання ключа не скидає вашу денну квоту — вона скидається опівночі за UTC.
5Помилки автентифікації
Відсутній, спотворений чи відкликаний ключ повертає 401 з машиночитаним кодом помилки та зрозумілим людині повідомленням. Якщо ваші запити раптом починають падати з 401, перевірте, що ключ не відкликано і що заголовок Authorization написаний точно як Bearer плюс пробіл плюс ключ.
Дійсний ключ, націлений на групу, якою ви не керуєте, повертає 404. Дійсний ключ на тарифі нижче Pro, що викликає ендпоінт лише для Pro, повертає 403 з кодом plan_required та підказкою про оновлення.
- 401 — ключ відсутній, спотворений чи відкликаний.
- 404 — цільова група не існує або ви не її адмін.
- 403 plan_required — ендпоінт потребує Pro чи вище на цій групі.