Cada petición a la API de Telm se autentica con una clave de API que empieza por tk_live_, nunca con tu inicio de sesión del panel. Crea una clave en tu cuenta, envíala en el encabezado Authorization como token Bearer, y actúa en nombre de tu cuenta sobre los grupos donde eres administrador. Si una clave se filtra, revócala en el panel y emite una nueva.
1Cómo funcionan las claves de API
La API REST de Telm no usa la sesión de tu navegador. En su lugar, cada petición lleva una clave de API, una larga cadena secreta que empieza por el prefijo tk_live_ seguido de caracteres aleatorios. La clave identifica tu cuenta y autoriza la llamada.
Generas claves desde tu cuenta y puedes tener varias a la vez (por ejemplo, una por script o servicio). El secreto completo se muestra solo una vez, en el momento de la creación; después el panel lista una clave por su prefijo corto (tk_live_ más los primeros caracteres) para que la reconozcas, y el valor completo nunca se conserva tras eso.
- Una clave tiene el aspecto de tk_live_ seguido de una larga cadena aleatoria.
- Las claves se crean y gestionan en tu panel.
- El secreto completo se muestra solo una vez: cópialo de inmediato y guárdalo en un lugar seguro.
- Trata una clave como una contraseña: cualquiera que la tenga puede llamar a la API como si fueras tú.
2Enviar la clave con cada petición
Pasa la clave en el encabezado Authorization usando el esquema Bearer. El valor del encabezado es la palabra Bearer, un espacio, y luego tu clave: por ejemplo, Authorization: Bearer tk_live_your_key_here.
Para clientes que no pueden fijar cómodamente un encabezado Authorization, la API también acepta la clave en un encabezado X-API-Key. Si ambos están presentes, gana el encabezado Authorization. Las peticiones sobre cualquier cosa que no sea HTTPS no se aceptan en producción.
- Preferido: envía Authorization: Bearer tk_live_...
- Alternativa: envía la clave en el encabezado X-API-Key en su lugar.
- La URL base de cada llamada es api.telm.com/api/public/v1.
- Consulta la lista completa de endpoints y esquemas en la página de desarrolladores.
3A qué puede acceder una clave
Una clave actúa estrictamente en nombre de tu cuenta. Solo puede leer o cambiar los grupos donde tu cuenta es administradora; una petición que apunta a cualquier otro grupo devuelve 404, así que la API nunca revela que un grupo que no puedes gestionar siquiera existe.
El acceso también depende del plan del grupo objetivo. El endpoint de comprobación de spam está abierto a todos los planes dentro de la cuota diaria, mientras que la API completa (reglas, ajustes, lista blanca, registro, analíticas, comprobaciones por lotes y webhooks) está disponible en el plan Pro o superior en el grupo implicado.
- Una clave solo puede tocar los grupos donde eres administrador.
- Las peticiones a grupos que no gestionas devuelven 404, no 403.
- La cuota diaria se comparte entre todas tus claves, contada por cuenta.
4Revocar y rotar claves
Si una clave queda expuesta (subida a un repositorio, pegada en un chat, o filtrada de cualquier otra forma), revócala de inmediato desde tu panel. La revocación surte efecto de inmediato: la clave revocada deja de funcionar en segundos, no tras algún retraso.
Como la cuota diaria se comparte por cuenta, revocar una clave no reinicia tu contador de uso. Rotar las claves con regularidad es buena higiene: crea la nueva clave, despliégala en tu servicio, confirma que funciona, luego revoca la antigua para que no haya tiempo de inactividad.
- Revoca una clave desde tu panel; deja de funcionar casi de inmediato.
- Crea el reemplazo primero, despliégalo, luego revoca la clave antigua para una rotación sin tiempo de inactividad.
- Revocar una clave no reinicia tu cuota diaria: esa se reinicia a medianoche UTC.
5Errores de autenticación
Una clave ausente, malformada o revocada devuelve 401 con un código de error legible por máquina y un mensaje legible por humanos. Si tus peticiones empiezan de repente a fallar con 401, comprueba que la clave no fue revocada y que el encabezado Authorization está escrito exactamente como Bearer más un espacio más la clave.
Una clave válida que apunta a un grupo que no gestionas devuelve 404. Una clave válida en un plan por debajo de Pro que llama a un endpoint solo de Pro devuelve 403 con un código plan_required y una pista de mejora.
- 401 — la clave está ausente, malformada o revocada.
- 404 — el grupo objetivo no existe o no eres su administrador.
- 403 plan_required — el endpoint necesita Pro o superior en ese grupo.