Setiap permintaan API Telm diautentikasi dengan sebuah kunci API yang diawali tk_live_ — bukan dengan login dashboard Anda. Buat sebuah kunci di akun Anda, kirim ia dalam header Authorization sebagai token Bearer, dan ia bertindak atas nama akun Anda pada grup tempat Anda menjadi admin. Jika sebuah kunci bocor, cabut ia di dashboard dan terbitkan yang baru.
1Cara kerja kunci API
REST API Telm tidak menggunakan sesi browser Anda. Sebagai gantinya, setiap permintaan membawa sebuah kunci API — string rahasia panjang yang diawali prefiks tk_live_ diikuti karakter acak. Kunci itu mengidentifikasi akun Anda dan mengotorisasi panggilan.
Anda menghasilkan kunci dari akun Anda dan dapat menyimpan beberapa sekaligus (misalnya, satu per skrip atau layanan). Rahasia lengkapnya ditampilkan hanya sekali, pada saat pembuatan; setelahnya dashboard mendaftarkan sebuah kunci berdasarkan prefiks pendeknya (tk_live_ plus karakter pertama) agar Anda dapat mengenalinya, dan nilai lengkapnya tidak pernah disimpan setelah itu.
- Sebuah kunci tampak seperti tk_live_ diikuti string acak yang panjang.
- Kunci dibuat dan dikelola di dashboard Anda.
- Rahasia lengkap ditampilkan hanya sekali — salin ia segera dan simpan di tempat yang aman.
- Perlakukan sebuah kunci seperti kata sandi: siapa pun yang memilikinya dapat memanggil API sebagai Anda.
2Mengirim kunci dengan setiap permintaan
Kirim kunci dalam header Authorization menggunakan skema Bearer. Nilai header adalah kata Bearer, sebuah spasi, lalu kunci Anda — misalnya, Authorization: Bearer tk_live_your_key_here.
Untuk klien yang tidak dapat mengatur header Authorization dengan nyaman, API juga menerima kunci dalam header X-API-Key. Jika keduanya ada, header Authorization yang menang. Permintaan melalui apa pun selain HTTPS tidak diterima di produksi.
- Disarankan: kirim Authorization: Bearer tk_live_...
- Alternatif: kirim kunci dalam header X-API-Key sebagai gantinya.
- URL dasar untuk setiap panggilan adalah api.telm.com/api/public/v1.
- Lihat daftar endpoint dan skema lengkap di halaman developer.
3Apa yang dapat diakses sebuah kunci
Sebuah kunci bertindak semata-mata atas nama akun Anda. Ia hanya dapat membaca atau mengubah grup tempat akun Anda menjadi admin — permintaan yang menargetkan grup lain mana pun mengembalikan 404, sehingga API tidak pernah mengungkap bahwa grup yang tidak dapat Anda kelola bahkan ada.
Akses juga bergantung pada paket grup target. Endpoint pemeriksaan spam terbuka untuk setiap paket dalam kuota harian, sementara API lengkap (aturan, pengaturan, whitelist, jurnal, analitik, pemeriksaan batch, dan webhook) tersedia pada paket Pro atau lebih tinggi pada grup yang bersangkutan.
- Sebuah kunci hanya dapat menyentuh grup tempat Anda menjadi admin.
- Permintaan ke grup yang tidak Anda kelola mengembalikan 404, bukan 403.
- Kuota harian dibagi di seluruh kunci Anda, dihitung per akun.
4Mencabut dan merotasi kunci
Jika sebuah kunci terekspos — dikomit ke repositori, ditempel ke obrolan, atau bocor dengan cara lain apa pun — cabut ia segera dari dashboard Anda. Pencabutan berlaku langsung: kunci yang dicabut berhenti bekerja dalam hitungan detik, bukan setelah penundaan.
Karena kuota harian dibagi per akun, mencabut satu kunci tidak mengatur ulang penghitung penggunaan Anda. Merotasi kunci secara berkala adalah higiene yang baik: buat kunci baru, terapkan ke layanan Anda, konfirmasikan ia bekerja, lalu cabut kunci lama agar tidak ada waktu henti.
- Cabut sebuah kunci dari dashboard Anda; ia berhenti bekerja hampir seketika.
- Buat penggantinya lebih dulu, luncurkan, lalu cabut kunci lama untuk rotasi tanpa waktu henti.
- Mencabut sebuah kunci tidak mengatur ulang kuota harian Anda — itu diatur ulang pada tengah malam UTC.
5Kesalahan autentikasi
Kunci yang hilang, salah bentuk, atau dicabut mengembalikan 401 dengan kode kesalahan yang dapat dibaca mesin dan pesan yang dapat dibaca manusia. Jika permintaan Anda tiba-tiba mulai gagal dengan 401, periksa bahwa kunci tidak dicabut dan bahwa header Authorization dieja persis sebagai Bearer plus sebuah spasi plus kunci.
Kunci yang valid yang menargetkan grup yang tidak Anda kelola mengembalikan 404. Kunci yang valid pada paket di bawah Pro yang memanggil endpoint khusus-Pro mengembalikan 403 dengan kode plan_required dan petunjuk peningkatan.
- 401 — kunci hilang, salah bentuk, atau dicabut.
- 404 — grup target tidak ada atau Anda bukan adminnya.
- 403 plan_required — endpoint membutuhkan Pro atau lebih tinggi pada grup itu.