Ogni richiesta all'API di Telm è autenticata con una chiave API che inizia con tk_live_ — mai con il suo accesso alla dashboard. Crei una chiave nel suo account, la invii nell'header Authorization come token Bearer, e agirà per conto del suo account sui gruppi in cui è amministratore. Se una chiave viene compromessa, la revochi nella dashboard e ne emette una nuova.
1Come funzionano le chiavi API
La REST API di Telm non usa la sua sessione del browser. Invece, ogni richiesta trasporta una chiave API — una lunga stringa segreta che inizia con il prefisso tk_live_ seguito da caratteri casuali. La chiave identifica il suo account e autorizza la chiamata.
Genera le chiavi dal suo account e può tenerne diverse contemporaneamente (per esempio, una per script o servizio). Il segreto completo viene mostrato una sola volta, al momento della creazione; in seguito la dashboard elenca una chiave dal suo breve prefisso (tk_live_ più i primi caratteri) così può riconoscerla, e il valore completo non viene mai conservato dopo di allora.
- Una chiave si presenta come tk_live_ seguito da una lunga stringa casuale.
- Le chiavi vengono create e gestite nella sua dashboard.
- Il segreto completo viene visualizzato una sola volta — copialo immediatamente e conservalo in un luogo sicuro.
- Tratta una chiave come una password: chiunque la possieda può chiamare l'API come te.
2Inviare la chiave con ogni richiesta
Passa la chiave nell'header Authorization usando lo schema Bearer. Il valore dell'header è la parola Bearer, uno spazio e poi la sua chiave — per esempio, Authorization: Bearer tk_live_your_key_here.
Per i client che non possono impostare comodamente un header Authorization, l'API accetta la chiave anche in un header X-API-Key. Se entrambi sono presenti, prevale l'header Authorization. Le richieste su qualsiasi cosa diversa da HTTPS non vengono accettate in produzione.
- Preferito: invia Authorization: Bearer tk_live_...
- Alternativa: invia la chiave nell'header X-API-Key.
- L'URL di base per ogni chiamata è api.telm.com/api/public/v1.
- Vedi l'elenco completo degli endpoint e gli schemi sulla pagina per sviluppatori.
3A cosa può accedere una chiave
Una chiave agisce rigorosamente per conto del suo account. Può leggere o modificare solo i gruppi in cui il suo account è amministratore — una richiesta che punta a qualsiasi altro gruppo restituisce 404, così l'API non rivela mai che un gruppo che non può gestire esista addirittura.
L'accesso dipende anche dal piano del gruppo di destinazione. L'endpoint di controllo spam è aperto a ogni piano entro la quota giornaliera, mentre l'API completa (regole, impostazioni, whitelist, registro, analisi, controlli in batch e webhook) è disponibile sul piano Pro o superiore sul gruppo coinvolto.
- Una chiave può toccare solo i gruppi in cui è amministratore.
- Le richieste a gruppi che non gestisci restituiscono 404, non 403.
- La quota giornaliera è condivisa tra tutte le sue chiavi, conteggiata per account.
4Revocare e ruotare le chiavi
Se una chiave viene esposta — inserita in un repository, incollata in una chat o compromessa in qualsiasi altro modo — la revochi immediatamente dalla sua dashboard. La revoca ha effetto subito: la chiave revocata smette di funzionare nel giro di secondi, non dopo qualche ritardo.
Poiché la quota giornaliera è condivisa per account, revocare una chiave non azzera il suo contatore di utilizzo. Ruotare le chiavi regolarmente è una buona igiene: crei la nuova chiave, la distribuisca al suo servizio, confermi che funzioni, poi revochi quella vecchia così non c'è alcun tempo di inattività.
- Revochi una chiave dalla sua dashboard; smette di funzionare quasi immediatamente.
- Crea prima la sostituzione, distribuiscila, poi revoca la vecchia chiave per una rotazione senza tempi di inattività.
- Revocare una chiave non azzera la sua quota giornaliera — quella si azzera a mezzanotte UTC.
5Errori di autenticazione
Una chiave mancante, malformata o revocata restituisce 401 con un codice di errore leggibile dalla macchina e un messaggio leggibile dall'uomo. Se le sue richieste iniziano improvvisamente a fallire con 401, verifichi che la chiave non sia stata revocata e che l'header Authorization sia scritto esattamente come Bearer più uno spazio più la chiave.
Una chiave valida che punta a un gruppo che non gestisci restituisce 404. Una chiave valida su un piano inferiore a Pro che chiama un endpoint riservato a Pro restituisce 403 con un codice plan_required e un suggerimento di upgrade.
- 401 — la chiave è mancante, malformata o revocata.
- 404 — il gruppo di destinazione non esiste o non ne è amministratore.
- 403 plan_required — l'endpoint richiede Pro o superiore su quel gruppo.