Varje Telm API-anrop autentiseras med en API-nyckel som börjar med tk_live_ — aldrig med din inloggning till dashboarden. Skapa en nyckel i ditt konto, skicka den i Authorization-huvudet som en Bearer-token, och den agerar för ditt kontos räkning på de grupper där du är administratör. Om en nyckel läcker, återkalla den i dashboarden och utfärda en ny.
1Så fungerar API-nycklar
Telm REST API använder inte din webbläsarsession. Istället bär varje anrop en API-nyckel — en lång hemlig sträng som börjar med prefixet tk_live_ följt av slumpmässiga tecken. Nyckeln identifierar ditt konto och auktoriserar anropet.
Du genererar nycklar från ditt konto och kan ha flera samtidigt (till exempel en per skript eller tjänst). Den fullständiga hemligheten visas bara en gång, vid skapandet; därefter listar dashboarden en nyckel med sitt korta prefix (tk_live_ plus de första tecknen) så att du kan känna igen den, och det fullständiga värdet behålls aldrig efter det.
- En nyckel ser ut som tk_live_ följt av en lång slumpmässig sträng.
- Nycklar skapas och hanteras i din dashboard.
- Den fullständiga hemligheten visas bara en gång — kopiera den omedelbart och förvara den säkert.
- Behandla en nyckel som ett lösenord: den som har den kan anropa API:et som dig.
2Att skicka nyckeln med varje anrop
Skicka nyckeln i Authorization-huvudet med Bearer-schemat. Huvudets värde är ordet Bearer, ett mellanslag, och sedan din nyckel — till exempel Authorization: Bearer tk_live_din_nyckel_här.
För klienter som inte enkelt kan sätta ett Authorization-huvud accepterar API:et även nyckeln i ett X-API-Key-huvud. Om båda finns vinner Authorization-huvudet. Anrop över något annat än HTTPS accepteras inte i produktion.
- Föredraget: skicka Authorization: Bearer tk_live_...
- Alternativ: skicka nyckeln i X-API-Key-huvudet istället.
- Bas-URL:en för varje anrop är api.telm.com/api/public/v1.
- Se den fullständiga endpoint-listan och scheman på utvecklarsidan.
3Vad en nyckel kan komma åt
En nyckel agerar strikt för ditt kontos räkning. Den kan bara läsa eller ändra grupper där ditt konto är administratör — ett anrop som riktar sig mot någon annan grupp returnerar 404, så API:et avslöjar aldrig att en grupp du inte kan hantera ens existerar.
Åtkomsten beror också på målgruppens plan. Spamkontroll-endpointen är öppen för varje plan inom den dagliga kvoten, medan det fullständiga API:et (regler, inställningar, vitlista, journal, analys, batchkontroller och webhooks) är tillgängligt på Pro-planen eller högre på den berörda gruppen.
- En nyckel kan bara röra grupper där du är administratör.
- Anrop till grupper du inte hanterar returnerar 404, inte 403.
- Den dagliga kvoten delas över alla dina nycklar, räknad per konto.
4Att återkalla och rotera nycklar
Om en nyckel exponeras — checkas in i ett repository, klistras in i en chatt, eller läcker på något annat sätt — återkalla den omedelbart från din dashboard. Återkallelsen träder i kraft direkt: den återkallade nyckeln slutar fungera inom sekunder, inte efter någon fördröjning.
Eftersom den dagliga kvoten delas per konto nollställer inte återkallelse av en nyckel din användningsräknare. Att rotera nycklar regelbundet är god hygien: skapa den nya nyckeln, distribuera den till din tjänst, bekräfta att den fungerar, återkalla sedan den gamla så att det inte blir någon driftstopp.
- Återkalla en nyckel från din dashboard; den slutar fungera nästan omedelbart.
- Skapa ersättningen först, rulla ut den, återkalla sedan den gamla nyckeln för rotation utan driftstopp.
- Att återkalla en nyckel nollställer inte din dagliga kvot — den nollställs vid midnatt UTC.
5Autentiseringsfel
En saknad, felaktig eller återkallad nyckel returnerar 401 med en maskinläsbar felkod och ett människoläsbart meddelande. Om dina anrop plötsligt börjar misslyckas med 401, kontrollera att nyckeln inte återkallades och att Authorization-huvudet är stavat exakt som Bearer plus ett mellanslag plus nyckeln.
En giltig nyckel som riktar sig mot en grupp du inte hanterar returnerar 404. En giltig nyckel på en plan under Pro som anropar en endast-Pro-endpoint returnerar 403 med en plan_required-kod och ett uppgraderingstips.
- 401 — nyckeln saknas, är felaktig eller återkallad.
- 404 — målgruppen finns inte eller så är du inte dess administratör.
- 403 plan_required — endpointen kräver Pro eller högre på den gruppen.