Każde żądanie do Telm API jest uwierzytelniane kluczem API, który zaczyna się od tk_live_ — nigdy loginem do panelu. Utwórz klucz na swoim koncie, wyślij go w nagłówku Authorization jako token Bearer, a działa on w imieniu Twojego konta na grupach, w których jesteś administratorem. Jeśli klucz wycieknie, unieważnij go w panelu i wydaj nowy.
1Jak działają klucze API
Telm REST API nie używa Twojej sesji przeglądarki. Zamiast tego każde żądanie niesie klucz API — długi tajny ciąg, który zaczyna się od prefiksu tk_live_ i po nim losowe znaki. Klucz identyfikuje Twoje konto i autoryzuje wywołanie.
Klucze generujesz na swoim koncie i możesz mieć kilka naraz (na przykład jeden na skrypt lub usługę). Pełny sekret pokazywany jest tylko raz, w chwili utworzenia; potem panel wymienia klucz po jego krótkim prefiksie (tk_live_ plus pierwsze znaki), abyś mógł go rozpoznać, a pełna wartość nie jest już później przechowywana.
- Klucz wygląda jak tk_live_, po którym następuje długi losowy ciąg.
- Klucze są tworzone i zarządzane w Twoim panelu.
- Pełny sekret jest wyświetlany tylko raz — skopiuj go od razu i przechowuj w bezpiecznym miejscu.
- Traktuj klucz jak hasło: każdy, kto go ma, może wywoływać API jako Ty.
2Wysyłanie klucza z każdym żądaniem
Przekaż klucz w nagłówku Authorization, używając schematu Bearer. Wartością nagłówka jest słowo Bearer, spacja, a potem Twój klucz — na przykład Authorization: Bearer tk_live_your_key_here.
Dla klientów, którzy nie mogą wygodnie ustawić nagłówka Authorization, API akceptuje też klucz w nagłówku X-API-Key. Jeśli obecne są oba, wygrywa nagłówek Authorization. Żądania przez cokolwiek innego niż HTTPS nie są akceptowane w środowisku produkcyjnym.
- Zalecane: wyślij Authorization: Bearer tk_live_...
- Alternatywa: wyślij klucz w nagłówku X-API-Key zamiast tego.
- Bazowy URL każdego wywołania to api.telm.com/api/public/v1.
- Zobacz pełną listę endpointów i schematy na stronie dla deweloperów.
3Do czego klucz ma dostęp
Klucz działa ściśle w imieniu Twojego konta. Może czytać lub zmieniać tylko grupy, w których Twoje konto jest administratorem — żądanie celujące w jakąkolwiek inną grupę zwraca 404, więc API nigdy nie ujawnia, że grupa, której nie możesz zarządzać, w ogóle istnieje.
Dostęp zależy też od planu grupy docelowej. Endpoint sprawdzania spamu jest otwarty dla każdego planu w ramach dziennego limitu, podczas gdy pełne API (reguły, ustawienia, biała lista, dziennik, analityka, sprawdzenia wsadowe i webhooki) jest dostępne w planie Pro lub wyższym na zaangażowanej grupie.
- Klucz może dotykać tylko grup, w których jesteś administratorem.
- Żądania do grup, których nie zarządzasz, zwracają 404, a nie 403.
- Dzienny limit jest współdzielony przez wszystkie Twoje klucze, liczony per konto.
4Unieważnianie i rotacja kluczy
Jeśli klucz zostanie ujawniony — wgrany do repozytorium, wklejony na czat lub wyciekł w jakikolwiek inny sposób — unieważnij go natychmiast ze swojego panelu. Unieważnienie działa od razu: unieważniony klucz przestaje działać w ciągu sekund, a nie po jakimś opóźnieniu.
Ponieważ dzienny limit jest współdzielony per konto, unieważnienie jednego klucza nie resetuje licznika zużycia. Regularna rotacja kluczy to dobra higiena: utwórz nowy klucz, wdróż go do swojej usługi, potwierdź, że działa, a potem unieważnij stary, tak by nie było przestoju.
- Unieważnij klucz ze swojego panelu; przestaje działać niemal natychmiast.
- Najpierw utwórz zastępczy, wdróż go, a potem unieważnij stary klucz dla rotacji bez przestojów.
- Unieważnienie klucza nie resetuje dziennego limitu — ten resetuje się o północy UTC.
5Błędy uwierzytelniania
Brakujący, źle sformułowany lub unieważniony klucz zwraca 401 z maszynowo czytelnym kodem błędu i czytelnym dla człowieka komunikatem. Jeśli Twoje żądania nagle zaczynają zawodzić z 401, sprawdź, czy klucz nie został unieważniony i czy nagłówek Authorization jest zapisany dokładnie jako Bearer plus spacja plus klucz.
Prawidłowy klucz celujący w grupę, której nie zarządzasz, zwraca 404. Prawidłowy klucz w planie poniżej Pro, który wywołuje endpoint tylko dla Pro, zwraca 403 z kodem plan_required i podpowiedzią o ulepszeniu.
- 401 — klucz jest brakujący, źle sformułowany lub unieważniony.
- 404 — grupa docelowa nie istnieje lub nie jesteś jej administratorem.
- 403 plan_required — endpoint wymaga Pro lub wyższego na tej grupie.