Kimlik ve Yetki
Kimlik doğrulama
API anahtarı, oturum token'ı ve herkese açık uçlar — hangisi ne zaman, ve çalışma alanı nasıl çözülür.
Blesyum'da dört ayrı kapı vardır ve her uç bunlardan tam olarak birini bekler. Yanlış kapıdan girmeye çalışmak 401 ya da 403 üretir — ikisi farklı şeyler söyler, karıştırma.
API anahtarı (PAT)
Sunucudan sunucuya otomasyon içindir. Panelden üretilir, blsk_ önekiyle başlar.
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts" \
-H "Authorization: Bearer blsk_..."Üç şey bilmen gerekiyor:
1. Çalışma alanı ANAHTARDAN çözülür, adresten değil. Bu bir güvenlik kararıdır: bir anahtar yalnız kendi çalışma alanını görür. Başka bir kiracının host'una istek atsan bile kendi verini alırsın — çapraz kiracı sızıntısı mimari olarak imkânsızdır.
2. Kapsam (scope) uçları açar. Anahtarında contacts.read yoksa kişi listeleme ucu 403 döner. Kapsam listesi Kapsamlar sayfasında.
3. Anahtarın bir ortamı vardır. test ortamındaki bir anahtar canlı yan etkileri tetiklemez: webhook teslimatı yapılmaz, e-posta gönderilmez. Yani entegrasyonunu gerçek veriyle ama sessizce deneyebilirsin.
Gizli anahtar bir kez gösterilir ve veritabanında yalnız özeti saklanır. Anahtarı istemci tarafı koda (tarayıcı, mobil uygulama) gömme — orada saklanan bir sır, sır değildir.
Oturum token'ı
Panelin kendi uçları içindir. Kullanıcı giriş yapar, çekirdek bir oturum token'ı verir ve modüller o token'ı doğrular.
curl "https://acme.crm.blesyum.app/api/crm/v1/workspace" \
-H "Authorization: Bearer <oturum-token>"Bu token'ı bir entegrasyonda kullanmak tavsiye edilmez: kayan bir zaman aşımıyla ölür (varsayılan 1 gün; "beni hatırla" ile 14 gün), iki adımlı doğrulamaya tabidir ve kullanıcının parolası değişince iptal edilir. Otomasyon için API anahtarı kullan.
Herkese açık uçlar
Kimlik istemeyen uçlar vardır ve hepsinin bir sebebi var:
| Uç ailesi | Neden açık |
|---|---|
/healthz · /readyz · /metrics | Altyapı yoklaması |
| Webhook girişleri | Karşı taraf bizim kimliğimizi taşımaz; doğrulama imzayladır |
| Canlı sohbet widget'ı | Ziyaretçinin hesabı yoktur |
/api/v1/i18n/* | Giriş ekranının da çevrilmesi gerekir |
/api/v1/time | Saat referansı — DB'ye bile dokunmaz |
401 mi 403 mü
Bu ayrım entegrasyonun davranışını belirler:
| Kod | Anlamı | Ne yapmalısın |
|---|---|---|
401 | Kimlik yok ya da geçersiz | Anahtarı kontrol et; yeniden deneme |
403 | Kimlik geçerli, yetki yok | Kapsamı ya da lisansı kontrol et |
402 | Hesap açılışı tamamlanmadı | Panelden açılışı bitir |
429 | Hız sınırı | Retry-After kadar bekle |
403 gövdesindeki hint alanı makine okunurdur ve çevrilmez. Dallanmayı messagea göre yapma — o metin kullanıcının diline göre değişir.
İstek imzalama
Yüksek güvenlik gerektiren entegrasyonlar için anahtar isteğe bağlı olarak imzalı kullanılabilir. Bu, anahtarı ele geçiren birinin isteği yeniden oynatmasını (replay) engeller. Ayrıntı için panelde anahtarın detay ekranına bak.