Каждый запрос к API Telm аутентифицируется ключом API, который начинается с tk_live_, — никогда логином от дашборда. Создайте ключ в своём аккаунте, отправляйте его в заголовке Authorization как Bearer-токен, и он действует от имени вашего аккаунта в группах, где вы админ. Если ключ утёк, отзовите его в дашборде и выпустите новый.
1Как работают ключи API
REST API Telm не использует сессию вашего браузера. Вместо этого каждый запрос несёт ключ 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 или выше на этой группе.