API Anahtarları
Her dış entegrasyon, belirli bir BYNovax mağazasına ve belirli yetkilere bağlı bir API Client üzerinden çalışır. API Client için oluşturulan credential, External Commerce API isteklerinde kimlik doğrulama amacıyla kullanılır.
API anahtarı oluşturma veya yenileme sırasında yalnızca bir kez gösterilir. Daha sonra tekrar görüntülenemez.
API Client nedir?
- API Client, bir ERP, muhasebe yazılımı, entegratör veya özel uygulamanın BYNovax mağazasına bağlanmasını temsil eder.
- Bir mağazanın birden fazla API Client'ı olabilir.
- Örneğin aynı mağazada ERP, muhasebe yazılımı ve özel entegrasyon için ayrı API Client'lar kullanılabilir.
- Her API Client kendi credential ve scope yetkilerine sahiptir.
API anahtarı formatı
- Production credential'ları bnx_live_ prefix'i ile başlar.
- Credential, client kimliği ve secret bölümünden oluşur.
- Örnek format: bnx_live_<client-id>.<secret>
- Credential'ın tamamı gizli bilgi olarak değerlendirilmelidir.
Anahtar nasıl kullanılır?
- Önerilen yöntem Authorization header içinde Bearer credential kullanmaktır.
- Örnek: Authorization: Bearer bnx_live_<client-id>.<secret>
- BYNovax ayrıca uyumluluk amacıyla X-BYNovax-API-Key header'ını destekler.
- Yeni entegrasyonlarda Bearer authentication tercih edilmelidir.
Anahtar yalnızca bir kez gösterilir
- API credential oluşturulduğunda plaintext anahtar yalnızca oluşturma yanıtında gösterilir.
- Anahtar yenilendiğinde yeni credential yalnızca rotate yanıtında gösterilir.
- BYNovax plaintext secret'ı daha sonra tekrar göstermez.
- Anahtar kaybedilirse mevcut secret geri getirilemez; yeni bir anahtar oluşturulmalıdır.
Güvenli saklama
- API anahtarını yalnızca sunucu tarafında secret olarak saklayın.
- Git repository, frontend JavaScript, HTML, mobil uygulama veya herkese açık loglar içine yazmayın.
- Production ve test ortamlarında farklı credential kullanılması önerilir.
- Credential'ın yanlışlıkla açığa çıktığını düşünüyorsanız derhal rotate veya revoke işlemi uygulayın.
Mağaza / Tenant yetkisi
- Her credential doğrudan belirli bir BYNovax mağazasına bağlıdır.
- API isteğinde hangi mağazaya erişileceği credential üzerinden belirlenir.
- İstemci request body veya query içinde store_id göndererek başka mağazaya geçemez.
- Bu yapı tenant izolasyonunun temel güvenlik katmanlarından biridir.
Scope yetkileri
- API Client yalnızca kendisine verilen scope yetkileri kapsamında işlem yapabilir.
- Örneğin products:read yalnızca ürün okuma işlemlerine izin verir.
- inventory:write stok güncelleme işlemleri için gereklidir.
- webhooks:write webhook endpoint oluşturma veya silme işlemleri için gereklidir.
- Entegrasyona yalnızca ihtiyaç duyduğu minimum yetkilerin verilmesi önerilir.
Anahtar yenileme / Rotate
- Rotate işlemi API Client için yeni bir secret üretir.
- Yeni credential oluşturulduğu anda eski credential geçersiz hale gelir.
- Yeni anahtarı uygulamanızın secret store'una kaydettikten sonra eski anahtarı kullanmayı bırakın.
- Rotate işlemi API Client'ın mağaza veya scope bağlantısını değiştirmez.
Anahtar iptal etme / Revoke
- Revoke işlemi API Client'ın credential erişimini tamamen kapatır.
- İptal edilmiş credential ile yapılan External API çağrıları kimlik doğrulama hatası alır.
- Revoke edilen client geçmiş kayıtların korunması amacıyla fiziksel olarak silinmez.
- Artık kullanılmayan veya güvenliği şüpheli entegrasyonlar revoke edilmelidir.
401 ve 403
- 401 Unauthorized: credential eksik, geçersiz, süresi dolmuş, rotate edilmiş veya revoke edilmiş olabilir.
- 403 Forbidden: credential geçerlidir ancak endpoint için gerekli scope yetkisi yoktur.