Her Telm API isteği, tk_live_ ile başlayan bir API anahtarı ile kimlik doğrulanır — asla kontrol paneli girişinizle değil. Hesabınızda bir anahtar oluşturun, onu Authorization başlığında bir Bearer token olarak gönderin; anahtar, yönetici olduğunuz gruplarda hesabınız adına hareket eder. Bir anahtar sızarsa, kontrol panelinden iptal edin ve yeni bir tane çıkarın.
1API anahtarları nasıl çalışır
Telm REST API tarayıcı oturumunuzu kullanmaz. Bunun yerine her istek bir API anahtarı taşır — tk_live_ önekiyle başlayıp ardından rastgele karakterler gelen uzun bir gizli dizedir. Anahtar hesabınızı tanımlar ve çağrıyı yetkilendirir.
Anahtarları hesabınızdan üretirsiniz ve aynı anda birden fazlasını tutabilirsiniz (örneğin her komut dosyası veya hizmet için bir tane). Tam gizli değer yalnızca bir kez, oluşturma anında gösterilir; sonrasında kontrol paneli bir anahtarı kısa önekiyle (tk_live_ artı ilk karakterler) listeler ki onu tanıyabilesiniz, tam değer ise bundan sonra asla saklanmaz.
- Bir anahtar, tk_live_ ile ardından gelen uzun bir rastgele dize gibi görünür.
- Anahtarlar kontrol panelinizde oluşturulur ve yönetilir.
- Tam gizli değer yalnızca bir kez görüntülenir — onu hemen kopyalayın ve güvenli bir yerde saklayın.
- Bir anahtara bir parola gibi davranın: ona sahip olan herkes API'yi sizin adınıza çağırabilir.
2Anahtarı her istekle göndermek
Anahtarı, Bearer şemasını kullanarak Authorization başlığında iletin. Başlık değeri, Bearer kelimesi, bir boşluk ve ardından anahtarınızdır — örneğin, Authorization: Bearer tk_live_your_key_here.
Bir Authorization başlığını rahatça ayarlayamayan istemciler için API, anahtarı bir X-API-Key başlığında da kabul eder. İkisi de mevcutsa Authorization başlığı kazanır. Üretimde HTTPS dışında herhangi bir şey üzerinden gelen istekler kabul edilmez.
- Tercih edilen: Authorization: Bearer tk_live_... gönderin
- Alternatif: anahtarı bunun yerine X-API-Key başlığında gönderin.
- Her çağrı için temel URL api.telm.com/api/public/v1 adresidir.
- Tam uç nokta listesini ve şemaları geliştiriciler sayfasında görün.
3Bir anahtarın neye erişebileceği
Bir anahtar kesinlikle hesabınız adına hareket eder. Yalnızca hesabınızın yönetici olduğu grupları okuyabilir veya değiştirebilir — başka herhangi bir grubu hedefleyen bir istek 404 döndürür, dolayısıyla API yönetemediğiniz bir grubun var olduğunu bile asla açığa çıkarmaz.
Erişim ayrıca hedef grubun planına da bağlıdır. Spam kontrol uç noktası günlük kota dahilinde her plana açıktır, tam API (kurallar, ayarlar, beyaz liste, günlük, analitik, toplu kontroller ve web kancaları) ise ilgili grupta Pro planı veya üstünde kullanılabilir.
- Bir anahtar yalnızca yönetici olduğunuz gruplara dokunabilir.
- Yönetmediğiniz gruplara yapılan istekler 403 değil 404 döndürür.
- Günlük kota tüm anahtarlarınız arasında paylaşılır, hesap başına sayılır.
4Anahtarları iptal etme ve döndürme
Bir anahtar açığa çıkarsa — bir depoya işlenmiş, bir sohbete yapıştırılmış veya başka herhangi bir şekilde sızmışsa — kontrol panelinizden onu hemen iptal edin. İptal anında yürürlüğe girer: iptal edilen anahtar bir gecikmeyle değil, saniyeler içinde çalışmayı durdurur.
Günlük kota hesap başına paylaşıldığı için, bir anahtarı iptal etmek kullanım sayacınızı sıfırlamaz. Anahtarları düzenli döndürmek iyi bir hijyendir: yeni anahtarı oluşturun, hizmetinize dağıtın, çalıştığını doğrulayın, ardından kesinti olmasın diye eskisini iptal edin.
- Bir anahtarı kontrol panelinizden iptal edin; neredeyse anında çalışmayı durdurur.
- Kesintisiz döndürme için önce yedeği oluşturun, dağıtın, ardından eski anahtarı iptal edin.
- Bir anahtarı iptal etmek günlük kotanızı sıfırlamaz — bu, UTC gece yarısında sıfırlanır.
5Kimlik doğrulama hataları
Eksik, hatalı biçimlendirilmiş veya iptal edilmiş bir anahtar, makine tarafından okunabilir bir hata koduyla ve insan tarafından okunabilir bir mesajla 401 döndürür. İstekleriniz aniden 401 ile başarısız olmaya başlarsa, anahtarın iptal edilmediğini ve Authorization başlığının tam olarak Bearer artı bir boşluk artı anahtar şeklinde yazıldığını kontrol edin.
Yönetmediğiniz bir grubu hedefleyen geçerli bir anahtar 404 döndürür. Pro altında bir planda, yalnızca-Pro bir uç noktayı çağıran geçerli bir anahtar, bir plan_required koduyla ve bir yükseltme ipucuyla 403 döndürür.
- 401 — anahtar eksik, hatalı biçimlendirilmiş veya iptal edilmiş.
- 404 — hedef grup mevcut değil veya onun yöneticisi değilsiniz.
- 403 plan_required — uç nokta o grupta Pro veya üstünü gerektirir.