Jede Telm-API-Anfrage wird mit einem API-Schlüssel authentifiziert, der mit tk_live_ beginnt — nie mit Ihrem Dashboard-Login. Erstellen Sie einen Schlüssel in Ihrem Konto, senden Sie ihn im Authorization-Header als Bearer-Token, und er handelt im Namen Ihres Kontos in den Gruppen, in denen Sie Administrator sind. Wenn ein Schlüssel durchsickert, widerrufen Sie ihn im Dashboard und geben Sie einen neuen aus.
1So funktionieren API-Schlüssel
Die Telm-REST-API verwendet nicht Ihre Browser-Sitzung. Stattdessen trägt jede Anfrage einen API-Schlüssel — eine lange geheime Zeichenkette, die mit dem Präfix tk_live_ gefolgt von zufälligen Zeichen beginnt. Der Schlüssel identifiziert Ihr Konto und autorisiert den Aufruf.
Sie erzeugen Schlüssel in Ihrem Konto und können mehrere gleichzeitig halten (zum Beispiel einen pro Skript oder Dienst). Das vollständige Geheimnis wird nur einmal angezeigt, bei der Erstellung; danach listet das Dashboard einen Schlüssel anhand seines kurzen Präfixes auf (tk_live_ plus die ersten Zeichen), sodass Sie ihn erkennen können, und der vollständige Wert wird danach nie aufbewahrt.
- Ein Schlüssel sieht aus wie tk_live_ gefolgt von einer langen zufälligen Zeichenfolge.
- Schlüssel werden in Ihrem Dashboard erstellt und verwaltet.
- Das vollständige Geheimnis wird nur einmal angezeigt — kopieren Sie es sofort und bewahren Sie es sicher auf.
- Behandeln Sie einen Schlüssel wie ein Passwort: Wer ihn besitzt, kann die API in Ihrem Namen aufrufen.
2Den Schlüssel bei jeder Anfrage senden
Übergeben Sie den Schlüssel im Authorization-Header mit dem Bearer-Schema. Der Header-Wert ist das Wort Bearer, ein Leerzeichen und dann Ihr Schlüssel — zum Beispiel Authorization: Bearer tk_live_your_key_here.
Für Clients, die keinen Authorization-Header bequem setzen können, akzeptiert die API den Schlüssel auch in einem X-API-Key-Header. Sind beide vorhanden, hat der Authorization-Header Vorrang. Anfragen über etwas anderes als HTTPS werden in der Produktion nicht akzeptiert.
- Bevorzugt: Authorization: Bearer tk_live_... senden.
- Alternative: den Schlüssel stattdessen im X-API-Key-Header senden.
- Die Basis-URL für jeden Aufruf ist api.telm.com/api/public/v1.
- Die vollständige Endpunktliste und die Schemata finden Sie auf der Entwicklerseite.
3Worauf ein Schlüssel zugreifen kann
Ein Schlüssel handelt streng im Namen Ihres Kontos. Er kann nur Gruppen lesen oder ändern, in denen Ihr Konto Administrator ist — eine Anfrage, die auf eine andere Gruppe zielt, gibt 404 zurück, sodass die API niemals preisgibt, dass eine Gruppe, die Sie nicht verwalten können, überhaupt existiert.
Der Zugriff hängt außerdem vom Plan der Zielgruppe ab. Der Spam-Check-Endpunkt steht jedem Plan innerhalb des Tageskontingents offen, während die vollständige API (Regeln, Einstellungen, Whitelist, Journal, Analytics, Batch-Prüfungen und Webhooks) ab dem Pro-Plan für die betreffende Gruppe verfügbar ist.
- Ein Schlüssel kann nur Gruppen berühren, in denen Sie Administrator sind.
- Anfragen an Gruppen, die Sie nicht verwalten, geben 404 zurück, nicht 403.
- Das Tageskontingent wird über alle Ihre Schlüssel geteilt und pro Konto gezählt.
4Schlüssel widerrufen und rotieren
Wenn ein Schlüssel offengelegt wird — in ein Repository committet, in einen Chat eingefügt oder auf andere Weise durchgesickert —, widerrufen Sie ihn sofort in Ihrem Dashboard. Der Widerruf wird sofort wirksam: Der widerrufene Schlüssel funktioniert innerhalb von Sekunden nicht mehr, nicht erst nach einer Verzögerung.
Da das Tageskontingent pro Konto geteilt wird, setzt das Widerrufen eines Schlüssels Ihren Nutzungszähler nicht zurück. Schlüssel regelmäßig zu rotieren, ist gute Hygiene: Erstellen Sie den neuen Schlüssel, bringen Sie ihn in Ihren Dienst ein, bestätigen Sie, dass er funktioniert, und widerrufen Sie dann den alten, damit es keine Ausfallzeit gibt.
- Widerrufen Sie einen Schlüssel in Ihrem Dashboard; er funktioniert fast sofort nicht mehr.
- Erstellen Sie zuerst den Ersatz, rollen Sie ihn aus und widerrufen Sie dann den alten Schlüssel für eine Rotation ohne Ausfallzeit.
- Das Widerrufen eines Schlüssels setzt Ihr Tageskontingent nicht zurück — dieses wird um Mitternacht UTC zurückgesetzt.
5Authentifizierungsfehler
Ein fehlender, fehlerhafter oder widerrufener Schlüssel gibt 401 mit einem maschinenlesbaren Fehlercode und einer menschenlesbaren Meldung zurück. Wenn Ihre Anfragen plötzlich mit 401 fehlschlagen, prüfen Sie, ob der Schlüssel nicht widerrufen wurde und ob der Authorization-Header genau als Bearer plus Leerzeichen plus Schlüssel geschrieben ist.
Ein gültiger Schlüssel, der auf eine Gruppe zielt, die Sie nicht verwalten, gibt 404 zurück. Ein gültiger Schlüssel in einem Plan unterhalb von Pro, der einen ausschließlich Pro-Endpunkt aufruft, gibt 403 mit einem plan_required-Code und einem Upgrade-Hinweis zurück.
- 401 — der Schlüssel fehlt, ist fehlerhaft oder widerrufen.
- 404 — die Zielgruppe existiert nicht oder Sie sind nicht deren Administrator.
- 403 plan_required — der Endpunkt erfordert in dieser Gruppe Pro oder höher.