Každý požadavek Telm API je autentizován API klíčem, který začíná tk_live_ — nikdy vaším přihlášením do dashboardu. Vytvořte klíč ve svém účtu, odešlete ho v hlavičce Authorization jako Bearer token a jedná jménem vašeho účtu ve skupinách, kde jste správcem. Pokud klíč unikne, odvolejte ho v dashboardu a vydejte nový.
1Jak API klíče fungují
Telm REST API nepoužívá relaci vašeho prohlížeče. Místo toho každý požadavek nese API klíč — dlouhý tajný řetězec, který začíná předponou tk_live_ následovanou náhodnými znaky. Klíč identifikuje váš účet a autorizuje volání.
Klíče generujete ze svého účtu a můžete jich mít několik najednou (například jeden na skript nebo službu). Úplné tajemství se zobrazí pouze jednou, v okamžiku vytvoření; poté dashboard vypisuje klíč podle jeho krátké předpony (tk_live_ plus první znaky), abyste ho rozpoznali, a úplná hodnota se poté nikdy neuchovává.
- Klíč vypadá jako tk_live_ následovaný dlouhým náhodným řetězcem.
- Klíče se vytvářejí a spravují ve vašem dashboardu.
- Úplné tajemství se zobrazí pouze jednou — okamžitě ho zkopírujte a uložte na bezpečné místo.
- Zacházejte s klíčem jako s heslem: kdokoli, kdo ho má, může volat API jako vy.
2Odesílání klíče s každým požadavkem
Předejte klíč v hlavičce Authorization pomocí schématu Bearer. Hodnota hlavičky je slovo Bearer, mezera a poté váš klíč — například Authorization: Bearer tk_live_your_key_here.
Pro klienty, kteří nemohou pohodlně nastavit hlavičku Authorization, API přijímá klíč i v hlavičce X-API-Key. Pokud jsou přítomny obě, vyhrává hlavička Authorization. Požadavky přes cokoli jiného než HTTPS nejsou v produkci přijímány.
- Preferováno: odešlete Authorization: Bearer tk_live_...
- Alternativa: odešlete klíč místo toho v hlavičce X-API-Key.
- Základní URL pro každé volání je api.telm.com/api/public/v1.
- Úplný seznam koncových bodů a schémat najdete na stránce pro vývojáře.
3K čemu má klíč přístup
Klíč jedná striktně jménem vašeho účtu. Může číst nebo měnit pouze skupiny, kde je váš účet správcem — požadavek, který cílí na jakoukoli jinou skupinu, vrací 404, takže API nikdy neprozradí, že skupina, kterou nemůžete spravovat, vůbec existuje.
Přístup závisí i na tarifu cílové skupiny. Koncový bod pro kontrolu spamu je otevřený pro každý tarif v rámci denní kvóty, zatímco úplné API (pravidla, nastavení, seznam povolených, žurnál, analytika, dávkové kontroly a webhooky) je dostupné na tarifu Pro nebo vyšším na dané skupině.
- Klíč se může dotknout pouze skupin, kde jste správcem.
- Požadavky na skupiny, které nespravujete, vracejí 404, nikoli 403.
- Denní kvóta je sdílená napříč všemi vašimi klíči, počítána na účet.
4Odvolávání a rotace klíčů
Pokud je klíč vystaven — commitnut do repozitáře, vložen do chatu nebo unikl jakýmkoli jiným způsobem — okamžitě ho odvolejte ze svého dashboardu. Odvolání se projeví ihned: odvolaný klíč přestane fungovat během sekund, nikoli po nějakém zpoždění.
Protože denní kvóta je sdílená na účet, odvolání jednoho klíče neresetuje váš čítač spotřeby. Pravidelná rotace klíčů je dobrá hygiena: vytvořte nový klíč, nasaďte ho do své služby, potvrďte, že funguje, a poté odvolejte starý, aby nedošlo k výpadku.
- Odvolejte klíč ze svého dashboardu; přestane fungovat téměř okamžitě.
- Nejprve vytvořte náhradu, zaveďte ji a poté odvolejte starý klíč pro rotaci bez výpadku.
- Odvolání klíče neresetuje vaši denní kvótu — ta se resetuje o půlnoci UTC.
5Chyby autentizace
Chybějící, chybně formátovaný nebo odvolaný klíč vrací 401 se strojově čitelným kódem chyby a lidsky čitelnou zprávou. Pokud vaše požadavky náhle začnou selhávat s 401, zkontrolujte, že klíč nebyl odvolán a že je hlavička Authorization napsána přesně jako Bearer plus mezera plus klíč.
Platný klíč, který cílí na skupinu, kterou nespravujete, vrací 404. Platný klíč na tarifu pod Pro, který volá koncový bod pouze pro Pro, vrací 403 s kódem plan_required a nápovědou k upgradu.
- 401 — klíč chybí, je chybně formátovaný nebo odvolaný.
- 404 — cílová skupina neexistuje nebo nejste jejím správcem.
- 403 plan_required — koncový bod vyžaduje Pro nebo vyšší na dané skupině.