Elk Telm API-verzoek wordt geauthenticeerd met een API-sleutel die begint met tk_live_ — nooit met je dashboardlogin. Maak een sleutel in je account, verstuur die in de Authorization-header als Bearer-token, en die handelt namens je account op de groepen waar je beheerder bent. Als een sleutel lekt, trek hem dan in het dashboard in en geef een nieuwe uit.
1Hoe API-sleutels werken
De Telm REST API gebruikt niet je browsersessie. In plaats daarvan draagt elk verzoek een API-sleutel — een lange geheime tekenreeks die begint met de prefix tk_live_ gevolgd door willekeurige tekens. De sleutel identificeert je account en autoriseert de aanroep.
Je genereert sleutels vanuit je account en kunt er meerdere tegelijk aanhouden (bijvoorbeeld één per script of service). Het volledige geheim wordt slechts één keer getoond, bij het aanmaken; daarna vermeldt het dashboard een sleutel op zijn korte prefix (tk_live_ plus de eerste tekens) zodat je hem herkent, en de volledige waarde wordt daarna nooit bewaard.
- Een sleutel ziet eruit als tk_live_ gevolgd door een lange willekeurige tekenreeks.
- Sleutels worden aangemaakt en beheerd in je dashboard.
- Het volledige geheim wordt slechts één keer getoond — kopieer het meteen en bewaar het ergens veilig.
- Behandel een sleutel als een wachtwoord: iedereen die hem heeft kan de API aanroepen als jij.
2De sleutel bij elk verzoek meesturen
Stuur de sleutel mee in de Authorization-header met het Bearer-schema. De headerwaarde is het woord Bearer, een spatie, en daarna je sleutel — bijvoorbeeld Authorization: Bearer tk_live_your_key_here.
Voor clients die niet gemakkelijk een Authorization-header kunnen instellen, accepteert de API de sleutel ook in een X-API-Key-header. Als beide aanwezig zijn, wint de Authorization-header. Verzoeken over iets anders dan HTTPS worden in productie niet geaccepteerd.
- Aanbevolen: stuur Authorization: Bearer tk_live_...
- Alternatief: stuur de sleutel in plaats daarvan in de X-API-Key-header.
- De basis-URL voor elke aanroep is api.telm.com/api/public/v1.
- Zie de volledige lijst met endpoints en schema's op de ontwikkelaarspagina.
3Waar een sleutel toegang toe heeft
Een sleutel handelt strikt namens je account. Hij kan alleen groepen lezen of wijzigen waar je account beheerder is — een verzoek dat op een andere groep is gericht geeft 404, dus de API onthult nooit dat een groep die je niet kunt beheren zelfs maar bestaat.
Toegang hangt ook af van het plan van de doelgroep. Het spam-check-endpoint staat open voor elk plan binnen het dagelijkse quotum, terwijl de volledige API (regels, instellingen, whitelist, journaal, analytics, batch-controles en webhooks) beschikbaar is op het Pro-plan of hoger op de betrokken groep.
- Een sleutel kan alleen groepen raken waar je beheerder bent.
- Verzoeken aan groepen die je niet beheert geven 404, niet 403.
- Het dagelijkse quotum wordt gedeeld over al je sleutels, geteld per account.
4Sleutels intrekken en roteren
Als een sleutel wordt blootgesteld — vastgelegd in een repository, in een chat geplakt, of op welke andere manier dan ook gelekt — trek hem dan onmiddellijk in vanuit je dashboard. Intrekken heeft meteen effect: de ingetrokken sleutel stopt binnen seconden met werken, niet na enige vertraging.
Omdat het dagelijkse quotum per account wordt gedeeld, reset het intrekken van één sleutel je gebruiksteller niet. Sleutels regelmatig roteren is goede hygiëne: maak de nieuwe sleutel aan, implementeer die in je service, bevestig dat hij werkt, en trek daarna de oude in zodat er geen downtime is.
- Trek een sleutel in vanuit je dashboard; hij stopt vrijwel meteen met werken.
- Maak de vervanger eerst aan, rol hem uit, en trek daarna de oude sleutel in voor rotatie zonder downtime.
- Een sleutel intrekken reset je dagelijkse quotum niet — dat reset om middernacht UTC.
5Authenticatiefouten
Een ontbrekende, misvormde of ingetrokken sleutel geeft 401 met een machineleesbare foutcode en een menselijk leesbaar bericht. Als je verzoeken plotseling met 401 gaan falen, controleer dan of de sleutel niet is ingetrokken en of de Authorization-header exact is gespeld als Bearer plus een spatie plus de sleutel.
Een geldige sleutel die op een groep is gericht die je niet beheert geeft 404. Een geldige sleutel op een plan onder Pro die een alleen-Pro-endpoint aanroept geeft 403 met een plan_required-code en een upgrade-hint.
- 401 — de sleutel ontbreekt, is misvormd of is ingetrokken.
- 404 — de doelgroep bestaat niet of je bent er geen beheerder van.
- 403 plan_required — het endpoint vereist Pro of hoger op die groep.