Kimlik doğrulama

Her istek bir API anahtarı gerektirir. Anahtarı Authorization başlığında gönderin:

Authorization: Bearer kai_live_...

Bir anahtar tek bir çalışma alanına aittir. İsteğin hangi çalışma alanını okuyup yazacağına anahtar karar verir, bu yüzden hiçbir istek çalışma alanı kimliği taşımaz.

Anahtar oluşturma

Kai’de Ayarlar (Settings) → API bölümüne gidin ve API anahtarı oluştur (Create API key) seçeneğini seçin. Anahtarı yalnızca bir hesap sahibi veya yönetici oluşturabilir. Kai tam anahtarı yalnızca bir kez gösterir. Kai anahtarın gizli yarısının sadece SHA-256 özetini saklar, bu yüzden anahtarı kimse tekrar okuyamaz, Kai destek ekibi de okuyamaz. Bir anahtarı kaybederseniz yenisini oluşturun ve eskisini iptal edin.

İzinler

Bir anahtar, onu oluştururken seçtiğiniz izinleri taşır. Her uç nokta, ihtiyaç duyduğu izni belirtir.

İzin	Anahtarın yapabildikleri
`contacts:read`	Kişileri okur ve dışa aktarır.
`contacts:write`	Kişi oluşturur, günceller, atar ve siler.
`attributes:read`	Çalışma alanı özelliklerini okur.
`attributes:write`	Çalışma alanı özelliği oluşturur, günceller ve arşivler.
`members:read`	Ekip listesini okur.
`conversations:read`	Bir kişinin konuşmalarını ve kanal listesini okur.
`conversations:write`	Konuşma atar ve atamayı kaldırır.
`templates:read`	Onaylı mesaj şablonlarını okur.
`messages:send`	Müşterilere şablon mesajı gönderir.

Bir yazma izni, karşılığındaki okuma iznini de kapsar. Bu nedenle contacts:write kişileri okur da, çünkü her yazma işlemi yazdığı kayıtla yanıt verir. messages:send de conversations:read ve templates:read izinlerini kapsar, çünkü her gönderim oluşturduğu konuşma ve mesajla yanıt verir.

Bu izinler, kişilerin Kai’deki rolleri değildir. Bir anahtarın rolü ve koltuğu yoktur. Bir anahtara, işi için gereken en küçük izin kümesini verin.

Anahtar değişikliği

Bir anahtarın adını veya izinlerini değiştirmek için Ayarlar (Settings) → API bölümünde anahtarın yanındaki Düzenle (Edit) seçeneğini seçin. Anahtarın kendisi değişmez, bu yüzden anahtarı tutan sistemler çalışmaya devam eder. Yeni izinler bir sonraki istekte geçerli olur. İptal edilmiş bir anahtarı değiştiremezsiniz. Yeniden kullanmak için yeni bir anahtar oluşturun.

Anahtar iptali

Ayarlar (Settings) → API bölümünde anahtarın yanındaki İptal et (Revoke) seçeneğini seçin. O anahtarla gelen bir sonraki istek 401 döner. Kai anahtarın adını listede tutar, böylece denetim kaydı eksiksiz kalır.

Hatalar

Kai her kimlik doğrulama hatasına aynı şekilde yanıt verir:

{ "error": { "type": "unauthorized", "message": "That API key is not valid." } }

Mesaj; var olmayan bir anahtar, iptal edilmiş bir anahtar ve süresi dolmuş bir anahtar için aynıdır. Bu bilinçli bir tercihtir: her durum için farklı bir mesaj, çağıran tarafın hangi anahtar kimliklerinin var olduğunu öğrenmesine imkan verirdi. Anahtar geçerli ancak izni yoksa yanıt 403 olur ve izni belirtir:

{
  "error": {
    "type": "forbidden",
    "message": "This key does not have the \"contacts:write\" permission."
  }
}

Aktarım

API yalnızca HTTPS kabul eder. Bir anahtarı URL’ye, sorgu parametresine veya kayıt satırına koymayın. Kai bir anahtarı asla e-posta ile göndermez.

Buradan başlayın

Kavramlar

Nasıl yapılır

Kimlik doğrulama

Anahtar oluşturma

İzinler

Anahtar değişikliği

Anahtar iptali

Hatalar

Aktarım

​Anahtar oluşturma

​İzinler

​Anahtar değişikliği

​Anahtar iptali

​Hatalar

​Aktarım

Anahtar oluşturma

İzinler

Anahtar değişikliği

Anahtar iptali

Hatalar

Aktarım