Chaque requête à l’API Telm est authentifiée avec une clé API qui commence par tk_live_ — jamais avec votre identifiant de tableau de bord. Créez une clé dans votre compte, envoyez-la dans l’en-tête Authorization comme jeton Bearer, et elle agit au nom de votre compte sur les groupes où vous êtes administrateur. Si une clé fuit, révoquez-la dans le tableau de bord et émettez-en une nouvelle.
1Comment fonctionnent les clés API
L’API REST Telm n’utilise pas votre session de navigateur. À la place, chaque requête porte une clé API — une longue chaîne secrète qui commence par le préfixe tk_live_ suivi de caractères aléatoires. La clé identifie votre compte et autorise l’appel.
Vous générez les clés depuis votre compte et pouvez en détenir plusieurs à la fois (par exemple, une par script ou service). Le secret complet n’est affiché qu’une seule fois, au moment de la création ; ensuite, le tableau de bord liste une clé par son court préfixe (tk_live_ plus les premiers caractères) afin que vous puissiez la reconnaître, et la valeur complète n’est plus jamais conservée après cela.
- Une clé ressemble à tk_live_ suivi d’une longue chaîne aléatoire.
- Les clés sont créées et gérées dans votre tableau de bord.
- Le secret complet n’est affiché qu’une seule fois — copiez-le immédiatement et stockez-le en lieu sûr.
- Traitez une clé comme un mot de passe : quiconque la possède peut appeler l’API en votre nom.
2Envoyer la clé à chaque requête
Passez la clé dans l’en-tête Authorization avec le schéma Bearer. La valeur de l’en-tête est le mot Bearer, une espace, puis votre clé — par exemple, Authorization: Bearer tk_live_your_key_here.
Pour les clients qui ne peuvent pas définir commodément un en-tête Authorization, l’API accepte aussi la clé dans un en-tête X-API-Key. Si les deux sont présents, l’en-tête Authorization l’emporte. Les requêtes sur autre chose que HTTPS ne sont pas acceptées en production.
- Préféré : envoyez Authorization: Bearer tk_live_...
- Alternative : envoyez plutôt la clé dans l’en-tête X-API-Key.
- L’URL de base pour chaque appel est api.telm.com/api/public/v1.
- Voir la liste complète des endpoints et les schémas sur la page développeurs.
3Ce à quoi une clé peut accéder
Une clé agit strictement au nom de votre compte. Elle ne peut lire ou modifier que les groupes où votre compte est administrateur — une requête qui vise tout autre groupe renvoie 404, si bien que l’API ne révèle jamais qu’un groupe que vous ne pouvez pas gérer existe seulement.
L’accès dépend aussi du plan du groupe visé. L’endpoint de vérification anti-spam est ouvert à tous les plans dans la limite du quota quotidien, tandis que l’API complète (règles, paramètres, liste blanche, journal, analytique, vérifications par lot et webhooks) est disponible sur le plan Pro ou supérieur sur le groupe concerné.
- Une clé ne peut toucher que les groupes où vous êtes administrateur.
- Les requêtes vers des groupes que vous ne gérez pas renvoient 404, pas 403.
- Le quota quotidien est partagé entre toutes vos clés, compté par compte.
4Révoquer et faire tourner les clés
Si une clé est exposée — versée dans un dépôt, collée dans une discussion, ou fuitée de toute autre manière — révoquez-la immédiatement depuis votre tableau de bord. La révocation prend effet aussitôt : la clé révoquée cesse de fonctionner en quelques secondes, pas après un quelconque délai.
Comme le quota quotidien est partagé par compte, révoquer une clé ne réinitialise pas votre compteur d’utilisation. Faire tourner les clés régulièrement est une bonne hygiène : créez la nouvelle clé, déployez-la sur votre service, confirmez qu’elle fonctionne, puis révoquez l’ancienne afin qu’il n’y ait aucune interruption.
- Révoquez une clé depuis votre tableau de bord ; elle cesse de fonctionner presque immédiatement.
- Créez d’abord le remplacement, déployez-le, puis révoquez l’ancienne clé pour une rotation sans interruption.
- Révoquer une clé ne réinitialise pas votre quota quotidien — celui-ci se réinitialise à minuit UTC.
5Erreurs d’authentification
Une clé manquante, malformée ou révoquée renvoie 401 avec un code d’erreur lisible par machine et un message lisible par un humain. Si vos requêtes se mettent soudain à échouer avec 401, vérifiez que la clé n’a pas été révoquée et que l’en-tête Authorization est écrit exactement comme Bearer plus une espace plus la clé.
Une clé valide qui vise un groupe que vous ne gérez pas renvoie 404. Une clé valide sur un plan en dessous de Pro qui appelle un endpoint réservé à Pro renvoie 403 avec un code plan_required et un indice de mise à niveau.
- 401 — la clé est manquante, malformée ou révoquée.
- 404 — le groupe visé n’existe pas ou vous n’en êtes pas administrateur.
- 403 plan_required — l’endpoint nécessite Pro ou supérieur sur ce groupe.