# 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](https://docs.infraio.xyz/tr/api-reference/authentication). - 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](https://docs.infraio.xyz/tr/webhooks/signature-verification). - 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 uygulamadır çünkü niyeti belgeler, ama scope'u bir güvenlik sınırı olarak değerlendirmeden önce aşağıdaki uyarıyı okuyun. > **Warning:** > > **Scope'lar henüz uygulanmıyor.** *Herhangi bir* scope'taki sızdırılmış > bir `sk_` anahtarı, satıcınız için *herhangi bir* `/b2b/v1/*` uç noktasını > çağırabilir. Bir `read` anahtarı bir iade oluşturmaktan engellenmez. Dar > scope'lar bir sızıntının zararını henüz **sınırlamaz**: güvenlik > planlaması için her secret anahtarı tam erişim olarak değerlendirin ve > bir sızıntıyı sınırlamak için hızlı rotation ve iptale güvenin (aşağıda). ## Rotation 1. **Yeni bir anahtar oluştur.** Panel → **Geliştiriciler → API anahtarları** → **+ Anahtar ekle**. Scope seçin. Panel secret'ı **bir kez** gösterir — hemen saklayın. 2. **Env var'larınızı tüm ortamlarda** yeni değere taşıyın. Dağıtın. 3. **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. 4. **Eski anahtarı iptal edin.** Aynı ekran → kebab menüsü → **İptal et**. > **Warning:** > > 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: 1. **Panel → Geliştiriciler → API anahtarları → [anahtar] → Şimdi iptal et.** Etki anlıktır; kayma süresi yoktur. 2. Bir yedek üretin ve dağıtın. 3. 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, contact@lartech.xyz 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**. - ❌ **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'ı** (örneğin platform tarafından uygulanan haftalık rotation). Rotation manueldir. ## Sırada ne var - [Kimlik doğrulama](https://docs.infraio.xyz/tr/api-reference/authentication) — B2B çağrıları için tam imzalama algoritması. - [Webhook'lar → İmza doğrulama](https://docs.infraio.xyz/tr/webhooks/signature-verification) — `whsec_`'in gelen event'lerde nasıl kullanıldığı.