API anahtarları

Üç tür kimlik bilgisi, üç tehdit modeli.

`pk_` — Publishable

Tarayıcıya gönderilmek üzere tasarlanmıştır. Her imzalı B2B isteğinde X-Client-ID başlığı olarak gönderilir, ayrıca istemci tarafı checkout açmaları için SDK paketine gömülür.
Hesabınızı tanımlayabilir; oturum oluşturamaz, diğer satıcıların verilerini okuyamaz veya yıkıcı bir şey tetikleyemez.
Sızdırılmış bir publishable key düşük şiddetli bir olaydır.

`sk_` — Secret (HMAC imzalama anahtarı)

Tüm B2B API çağrıları için HMAC-SHA256 imzalama anahtarı — bkz. Kimlik doğrulama.
Tel üzerinde asla seyahat etmez. Yalnızca türetilmiş istek başına imzası seyahat eder. Yani yalnızca depolama katmanındaki sızıntılar hakkında endişelenmeniz gerekir (env vars, git, loglar), taşıma katmanında değil.
Yalnızca sunucu. Bir tarayıcı paketinde, public depoda, ekran görüntüsünde veya sohbet mesajında asla görünmemelidir.
Sızdırılmış bir secret yüksek şiddetli bir olaydır.

`whsec_` — Webhook imzalama secret’ı

Bizden sunucunuza yapılan gelen webhook teslimlerinde imzayı doğrulamak için kullanılır. Bkz. İmza doğrulama.
Webhook uç noktası başına ayrıdır — kayıtlı 3 uç noktanız varsa, 3 farklı whsec_ secret’ınız vardır. Ortam önekte kodlanır: whsec_live_… / whsec_test_….
Yalnızca sunucu. sk_ gibi, tel üzerinde asla seyahat etmez — yalnızca HMAC’leri yerel olarak doğrulamak için kullanılır.
Rotation’ın 24 saatlik bir kayma penceresi vardır. Rotate’a tıklayın ve önceki secret yeni olanın yanında 24 saat boyunca kabul edilmeye devam eder (teslimler hem X-Signature hem de X-Signature-Prev taşır), böylece trafiği tutmadan doğrulayıcınızı yeniden dağıtabilirsiniz.
Mevcut-secret’i göster mevcuttur, yeni 2FA ile korunur ve denetim günlüğüne kaydedilir — secret’ın kaybedildiği ve rotation’ın kabul edilemediği durum için. Panel’in varsayılan duruşu “rotate et, gösterme”dir.
Sızdırılmış bir webhook secret’ı, bir saldırganın URL’nize sahte event’ler yapmasına izin verir. Event payload’una ne kadar güvendiğinize bağlı olarak orta-yüksek şiddetli.

Scope’lar

Secret anahtarlar scope’ludur. Panel, bu scope demetlerinden biriyle anahtarlar üretmenize olanak tanır:

Scope	Yapabilir	Şunun için kullanılır
`read`	Siparişleri, oturumları, iadeleri, bakiyeleri listele/oku	Yalnızca-okuma entegrasyonları (analitik, BI)
`write_order`	Tüm `read` + oturum oluştur, sipariş oluştur, sipariş iptal et	Mağaza backend’i
`write_refund`	Tüm `read` + iade oluştur, iadeleri yürütüldü olarak işaretle	Müşteri destek araçları
`webhook_manage`	Tüm `read` + webhook uç noktalarını yönet	DevOps araçları

Varsayılan-üretim bir “tam erişim” anahtarı dördünü de alır. Amaç başına anahtarlar üretmek hâlâ iyi bir hijyendir — niyeti belgeler ve uygulama geldiğinde sizi hazırlar — ama scope’u bir güvenlik sınırı olarak değerlendirmeden önce aşağıdaki uyarıyı okuyun.

Scope’lar bugün tavsiye niteliğindedir — geçidde uygulanmazlar. Geçit, anahtarın HMAC imzasını doğrular ve satıcı kimliğinizi (X-Merchant-ID / X-Merchant-Domain) alt servislere enjekte eder, ancak anahtarın scope’unu propagate etmez veya kontrol etmez. Pratikte bu, herhangi bir scope’taki sızdırılmış bir sk_’nin satıcınız için herhangi bir /b2b/v1/* uç noktasını çağırabileceği anlamına gelir — bir read anahtarı, fiilen bir iade oluşturmaktan engellenmez. Bu yüzden dar scope’lar etki yarıçapını henüz sınırlamaz: ihlal planlaması için her secret anahtarı tam erişim olarak değerlendirin ve bu arada gerçek kapsam kontrolünüz olarak hızlı rotation + iptale güvenin (aşağıda). Scope başına uygulama yol haritasında.

Rotation

Yeni bir anahtar oluştur. Panel → Geliştiriciler → API anahtarları → + Anahtar ekle. Scope seçin. Panel secret’ı bir kez gösterir — hemen saklayın.
Env var’larınızı tüm ortamlarda yeni değere taşıyın. Dağıtın.
Trafiği doğrulayın. Panel anahtar başına istek sayılarını gerçek zamanlı gösterir. Eski anahtarın sayısının sıfıra düşmesini bekleyin.
Eski anahtarı iptal edin. Aynı ekran → kebab menüsü → İptal et.

Bugün otomatik bir çakışma penceresi yoktur — bir anahtarı iptal ettiğinizde, onunla imzalanmış uçuştaki herhangi bir istek 401 alır. Rotation’ınızı buna göre planlayın: önce yeni anahtarı dağıtın, trafiği eskiden boşaltın, sonra iptal edin.

Acil durum iptali

Bir anahtar sızdıysa (git geçmişinde, public bir pakette, loglanmış bir stack trace’te, bir partnerin pen-test raporunda) — bazı başarısız isteklerin maliyetine bile, hemen iptal edin. Bir saldırganın geçerli bir kimlik bilgisi tutmasına izin vermektense yüksek sesle başarısız olmak daha iyidir.

Adımlar:

Panel → Geliştiriciler → API anahtarları → [anahtar] → Şimdi iptal et. Etki anlıktır; kayma süresi yoktur.
Bir yedek üretin ve dağıtın.
Son etkinliği denetleyin — panel, anahtar başına son 30 günlük istekleri, vurulan IP’ler ve uç noktalarla gösterir.

İhlalin bir anahtardan daha geniş olduğundan şüpheleniyorsanız, [email protected] ile iletişime geçin:

Satıcı hesabınız için tam denetim günlüğü dışa aktarımı alın
Webhook secret’larını toplu olarak rotate edin
İsteğe bağlı olarak siz araştırırken hesabı dondurun

Saklama en iyi uygulamaları

Yalnızca env var’ları. Secret’ları git’e asla commit etmeyin, “REPLACE ME” yazan bir .env.example’da bile.
Ortam başına anahtarlar. Dev/staging/prod için farklı sk_test_… ve sk_live_…, secrets manager’ınızdan (AWS Secrets Manager, Vault, Doppler, …) kaynaklanır.
Env var erişimini kısıtlayın. Kubernetes’te bir ConfigMap olarak değil, bir Secret olarak monte edin. Vercel/Netlify’da proje genelinde global’ler yerine environment-variable scope’lamayı kullanın.
Gövdeli istekleri loglamayın. Hata ayıklarken bile — X-Signature içindeki HMAC imzanız tek kullanımlıktır ama işletme payload’unuz PII içerebilir.

Bugün NE desteklenmiyor

❌ Secret anahtarlar için IP allowlist’leme. Yol haritasında.
❌ OAuth stili scope’lu kullanıcı başına token’lar. Mevcut anahtar modeli satıcı başınadır, kullanıcı başına değil.
❌ Otomatik anahtar rotation’ı (örn. platform tarafından uygulanan haftalık rotation). Bugün manuel.

Sırada ne var

Kimlik doğrulama — B2B çağrıları için tam imzalama algoritması.
Webhook’lar → İmza doğrulama — whsec_’in gelen event’lerde nasıl kullanıldığı.