Kimlik ve Yetki
Kapsamlar
Bir API anahtarının hangi uçları açtığını kapsamlar belirler. Katalog tek kaynaktadır ve lisansına göre daralır.
Kapsam (scope), bir API anahtarının ne yapabileceğini söyler. Anahtar üretirken seçersin; seçmediğin bir kapsamın ucu 403 döner.
Nasıl çalışır
Kapsamlar <kaynak>.<eylem> biçimindedir: contacts.read, conversations.write. Bir uç kendi kapsamını ister; anahtarında yoksa istek reddedilir.
{ "type": "error.list",
"errors": [{ "code": "forbidden", "message": "Bu anahtar contacts.write kapsamını taşımıyor." }] }* kapsamı tümünü kapsar ve yalnız denetim kaydı tutulan yönetim anahtarlarında kullanılır. Günlük entegrasyonda dar kapsam seç: sızan bir anahtarın verebileceği zarar, taşıdığı kapsam kadardır.
Katalog
Kapsam listesi tek kaynakta yaşar ve üç yer aynı listeyi okur: anahtarı üreten panel, kapsamı doğrulayan modül ve bu doküman. Panelde gördüğün liste, sunucunun kabul ettiği listedir.
Liste lisansına göre daralır. Aboneliğinde CRM yoksa contacts.* kapsamları listede hiç görünmez — seçilebilen ama hiçbir kapıyı açmayan bir kapsam kullanıcıya yalan söylerdi.
Güncel kataloğu her zaman panelden görebilirsin:
Panel → Geliştirici → API Anahtarları → Yeni anahtar
Ya da uçtan:
curl "https://accounts.blesyum.com/api/v1/apikeys/scopes" \
-H "Authorization: Bearer <oturum-token>"Çekirdek kapsamları
| Kapsam | Ne açar |
|---|---|
core.read | Çekirdek kaynakları okur |
core.write | Çekirdek kaynak oluşturur / günceller |
CRM kapsamları
| Kapsam | Ne açar |
|---|---|
contacts.read · contacts.write | Kişiler |
conversations.read · conversations.write | Görüşmeler |
messages.write | Görüşmeye mesaj yollar |
events.read · events.write | Olay akışı |
data_attributes.read · data_attributes.write | Özel öznitelik tanımları |
webhooks.manage | Webhook uçlarını API üzerinden yönetir |
Yeni bir modül public API'si açıldığında kapsamları kendiliğinden bu listeye girer — katalog tek kaynaktan okunur, elle güncellenmez.
Yanlış yazım sessizce geçmez
Katalogda olmayan bir kapsamla anahtar üretmeye çalışırsan uç 400 döner. Bu bilinçli bir kapıdır: eskiden doğrulama yoktu ve contats.read yazan biri 201 alıyor, sonra günlerce "anahtarım çalışmıyor" diye arıyordu.