Setiap permintaan API Telm disahkan dengan kunci API yang bermula dengan tk_live_ — tidak pernah dengan log masuk papan pemuka anda. Cipta kunci dalam akaun anda, hantarkannya dalam pengepala Authorization sebagai token Bearer, dan ia bertindak bagi pihak akaun anda pada kumpulan di mana anda seorang pentadbir. Jika kunci bocor, batalkannya dalam papan pemuka dan keluarkan yang baharu.
1Bagaimana kunci API berfungsi
API REST Telm tidak menggunakan sesi pelayar anda. Sebaliknya, setiap permintaan membawa kunci API — rentetan rahsia panjang yang bermula dengan awalan tk_live_ diikuti oleh aksara rawak. Kunci itu mengenal pasti akaun anda dan membenarkan panggilan.
Anda menjana kunci dari akaun anda dan boleh memegang beberapa serentak (contohnya, satu setiap skrip atau perkhidmatan). Rahsia penuh ditunjukkan hanya sekali, pada masa penciptaan; selepas itu papan pemuka menyenaraikan kunci mengikut awalan pendeknya (tk_live_ ditambah aksara pertama) supaya anda boleh mengenalinya, dan nilai penuh tidak pernah disimpan selepas itu.
- Kunci kelihatan seperti tk_live_ diikuti oleh rentetan rawak panjang.
- Kunci dicipta dan diurus dalam papan pemuka anda.
- Rahsia penuh dipaparkan hanya sekali — salinnya serta-merta dan simpannya di suatu tempat yang selamat.
- Perlakukan kunci seperti kata laluan: sesiapa yang memilikinya boleh memanggil API sebagai anda.
2Menghantar kunci dengan setiap permintaan
Hantarkan kunci dalam pengepala Authorization menggunakan skema Bearer. Nilai pengepala ialah perkataan Bearer, satu ruang, dan kemudian kunci anda — contohnya, Authorization: Bearer tk_live_your_key_here.
Untuk klien yang tidak dapat menetapkan pengepala Authorization dengan mudah, API juga menerima kunci dalam pengepala X-API-Key. Jika kedua-duanya hadir, pengepala Authorization menang. Permintaan melalui apa-apa selain HTTPS tidak diterima dalam persekitaran produksi.
- Diutamakan: hantar Authorization: Bearer tk_live_...
- Alternatif: hantar kunci dalam pengepala X-API-Key sebaliknya.
- URL asas untuk setiap panggilan ialah api.telm.com/api/public/v1.
- Lihat senarai titik akhir penuh dan skema pada halaman pembangun.
3Apa yang boleh diakses oleh kunci
Kunci bertindak dengan ketat bagi pihak akaun anda. Ia hanya boleh membaca atau mengubah kumpulan di mana akaun anda ialah pentadbir — permintaan yang menyasarkan mana-mana kumpulan lain memulangkan 404, jadi API tidak pernah mendedahkan bahawa kumpulan yang anda tidak boleh urus itu wujud pun.
Akses juga bergantung pada pelan kumpulan sasaran. Titik akhir semakan spam terbuka kepada setiap pelan dalam kuota harian, manakala API penuh (peraturan, tetapan, senarai putih, jurnal, analitik, semakan berkelompok dan webhook) tersedia pada pelan Pro atau lebih tinggi pada kumpulan yang terlibat.
- Kunci hanya boleh menyentuh kumpulan di mana anda seorang pentadbir.
- Permintaan kepada kumpulan yang anda tidak urus memulangkan 404, bukan 403.
- Kuota harian dikongsi merentas semua kunci anda, dikira setiap akaun.
4Membatalkan dan memutar kunci
Jika kunci terdedah — dikomit ke repositori, ditampal ke dalam sembang, atau bocor dengan cara lain — batalkannya serta-merta dari papan pemuka anda. Pembatalan berkuat kuasa dengan segera: kunci yang dibatalkan berhenti berfungsi dalam beberapa saat, bukan selepas sebarang kelewatan.
Kerana kuota harian dikongsi setiap akaun, membatalkan satu kunci tidak menetapkan semula kaunter penggunaan anda. Memutar kunci secara berkala ialah kebersihan yang baik: cipta kunci baharu, gunakannya ke perkhidmatan anda, sahkan ia berfungsi, kemudian batalkan kunci lama supaya tiada masa henti.
- Batalkan kunci dari papan pemuka anda; ia berhenti berfungsi hampir serta-merta.
- Cipta pengganti dahulu, lancarkannya, kemudian batalkan kunci lama untuk putaran tanpa masa henti.
- Membatalkan kunci tidak menetapkan semula kuota harian anda — itu ditetapkan semula pada tengah malam UTC.
5Ralat pengesahan
Kunci yang hilang, cacat, atau dibatalkan memulangkan 401 dengan kod ralat boleh dibaca mesin dan mesej boleh dibaca manusia. Jika permintaan anda tiba-tiba mula gagal dengan 401, semak bahawa kunci itu tidak dibatalkan dan bahawa pengepala Authorization dieja tepat sebagai Bearer ditambah ruang ditambah kunci.
Kunci sah yang menyasarkan kumpulan yang anda tidak urus memulangkan 404. Kunci sah pada pelan di bawah Pro yang memanggil titik akhir Pro sahaja memulangkan 403 dengan kod plan_required dan petunjuk naik taraf.
- 401 — kunci hilang, cacat, atau dibatalkan.
- 404 — kumpulan sasaran tidak wujud atau anda bukan pentadbirnya.
- 403 plan_required — titik akhir memerlukan Pro atau lebih tinggi pada kumpulan itu.