Toda requisição à API do Telm é autenticada com uma chave de API que começa com tk_live_ — nunca com o login do seu painel. Crie uma chave na sua conta, envie-a no cabeçalho Authorization como um token Bearer, e ela age em nome da sua conta nos grupos onde você é admin. Se uma chave vazar, revogue-a no painel e emita uma nova.
1Como as chaves de API funcionam
A API REST do Telm não usa a sessão do seu navegador. Em vez disso, cada requisição carrega uma chave de API — uma longa string secreta que começa com o prefixo tk_live_ seguido de caracteres aleatórios. A chave identifica a sua conta e autoriza a chamada.
Você gera chaves na sua conta e pode ter várias ao mesmo tempo (por exemplo, uma por script ou serviço). O segredo completo é mostrado apenas uma vez, no momento da criação; depois, o painel lista uma chave pelo seu prefixo curto (tk_live_ mais os primeiros caracteres) para que você a reconheça, e o valor completo nunca é mantido depois disso.
- Uma chave se parece com tk_live_ seguido de uma longa string aleatória.
- As chaves são criadas e gerenciadas no seu painel.
- O segredo completo é exibido apenas uma vez — copie-o imediatamente e guarde-o em um lugar seguro.
- Trate uma chave como uma senha: qualquer um que a tenha pode chamar a API como você.
2Enviando a chave em cada requisição
Passe a chave no cabeçalho Authorization usando o esquema Bearer. O valor do cabeçalho é a palavra Bearer, um espaço e depois a sua chave — por exemplo, Authorization: Bearer tk_live_your_key_here.
Para clientes que não conseguem definir um cabeçalho Authorization convenientemente, a API também aceita a chave em um cabeçalho X-API-Key. Se ambos estiverem presentes, o cabeçalho Authorization vence. Requisições por qualquer coisa que não seja HTTPS não são aceitas em produção.
- Preferido: envie Authorization: Bearer tk_live_...
- Alternativa: envie a chave no cabeçalho X-API-Key em vez disso.
- A URL base de toda chamada é api.telm.com/api/public/v1.
- Veja a lista completa de endpoints e schemas na página de desenvolvedores.
3O que uma chave pode acessar
Uma chave age estritamente em nome da sua conta. Ela só pode ler ou alterar grupos onde a sua conta é admin — uma requisição que mira qualquer outro grupo retorna 404, então a API nunca revela que um grupo que você não pode gerenciar sequer existe.
O acesso também depende do plano do grupo alvo. O endpoint de verificação de spam é aberto a todos os planos dentro da cota diária, enquanto a API completa (regras, configurações, lista de permissões, registro, análises, verificações em lote e webhooks) está disponível no plano Pro ou superior no grupo envolvido.
- Uma chave só pode tocar grupos onde você é admin.
- Requisições a grupos que você não gerencia retornam 404, não 403.
- A cota diária é compartilhada por todas as suas chaves, contada por conta.
4Revogando e rotacionando chaves
Se uma chave é exposta — enviada a um repositório, colada em um chat, ou vazada de qualquer outra forma — revogue-a imediatamente no seu painel. A revogação entra em vigor na hora: a chave revogada para de funcionar em segundos, não depois de algum atraso.
Como a cota diária é compartilhada por conta, revogar uma chave não zera o seu contador de uso. Rotacionar chaves regularmente é uma boa higiene: crie a nova chave, implante-a no seu serviço, confirme que funciona, depois revogue a antiga para não haver tempo de inatividade.
- Revogue uma chave no seu painel; ela para de funcionar quase imediatamente.
- Crie a substituta primeiro, implante-a, depois revogue a chave antiga para uma rotação sem tempo de inatividade.
- Revogar uma chave não zera a sua cota diária — ela zera à meia-noite UTC.
5Erros de autenticação
Uma chave ausente, malformada ou revogada retorna 401 com um código de erro legível por máquina e uma mensagem legível por humano. Se as suas requisições de repente começarem a falhar com 401, verifique se a chave não foi revogada e se o cabeçalho Authorization está escrito exatamente como Bearer mais um espaço mais a chave.
Uma chave válida que mira um grupo que você não gerencia retorna 404. Uma chave válida em um plano abaixo do Pro que chama um endpoint exclusivo do Pro retorna 403 com um código plan_required e uma dica de upgrade.
- 401 — a chave está ausente, malformada ou revogada.
- 404 — o grupo alvo não existe ou você não é admin dele.
- 403 plan_required — o endpoint precisa de Pro ou superior naquele grupo.