Kimlik Doğrulama

Selwise'in HTTP uçları tarayıcıdan, sunucudan ve mobil uygulamadan çağrılır; her biri farklı bir yolla yetkilendirilir. Bu sayfa hangi çağrının hangi kimlikle yapılacağını, hangi başlığın ne anlama geldiğini ve bir istek reddedildiğinde nedenini nasıl okuyacağınızı anlatır. Uç noktaların tek tek listesi için Public API sayfasına bakın.

Taban adres

https://api.selwise.com/api/v1

Public uçların tamamı /public/ altındadır. Çoğu /public/sites/:siteKey/... biçimindedir. Sürüm öneki (/api/v1) her yolun başında zorunludur; data-api-url veya SDK ayarı olarak taban adresi verirseniz /api/v1 eksikse kendiliğinden eklenir.

Site anahtarı bir sır değildir

siteKey, bir kanalı adlandıran herkese açık tanımlayıcıdır. Tarayıcıda, sayfa kaynağında ve ağ isteklerinde görünür. Panelde Channels → Channel Overview ekranındaki Channel Key (Kanal Anahtarı) kartında bulunur.

Yalnızca siteKey bilmek hiçbir şeye yetki vermez; her uç aşağıdaki üç yoldan birini ister (ya da bilinçli olarak hiçbirini istemez, bkz. Doğrulamasız uçlar).

Üç erişim yolu

Yol	Kim kullanır	Nasıl doğrulanır
Alan adı doğrulaması	Web kanalında ziyaretçinin tarayıcısı	Origin başlığı, yoksa Referer başlığı kanalın doğrulanmış alan adıyla karşılaştırılır
Kanal API anahtarı	Sunucu, mobil uygulama, her zaman uygulama kanalı	x-selwise-api-key başlığı ve kapsam (scope) kontrolü
Amaca özel sunucu anahtarı	Sunucu taraflı render ve izin senkronizasyonu	Aynı başlık; başlığın varlığından bağımsız olarak her istekte zorunlu

1. Alan adı doğrulaması (web kanalı)

İstek Origin veya Referer başlığı taşıyorsa host şu kurala göre karşılaştırılır:

• Kanalın doğrulanmış alan adı ya da onun alt alan adları kabul edilir: magaza.com ile www.magaza.com ve tr.magaza.com eşleşir, kotu-magaza.com eşleşmez.
• Doğrulanmış alan adı takma adları (apex ile www, ikinci ülke hostu, staging) birincil alan adıyla aynı kuralla kabul edilir. Doğrulanmamış takma ad yetki vermez. Bkz. Alan Adı Doğrulama.
• localhost, 127.0.0.1 ve [::1] yalnızca üretim dışı ortamlarda kabul edilir. Üretimde bu kapatılamaz: açık olsaydı herkes kendi makinesinden sizin sitenizin adına veri gönderebilirdi. Yerel geliştirme için ayrı bir test kanalı tanımlayın.

Tarayıcılar bu başlıkları kendiliğinden ekler; widget'ın yaptığı çağrıların hepsi bu yoldan geçer.

2. Kanal API anahtarı

İstek ne Origin ne Referer taşıyorsa (sunucudan veya yerel uygulamadan gelen istek) x-selwise-api-key başlığı aranır:

GET /api/v1/public/sites/SITE_KEY/config
x-selwise-api-key: swpk_live_...

Anahtarın kapsamı HTTP yöntemine göre seçilir:

Yöntem	Gereken kapsam
GET	mobile_read
POST, PUT, DELETE	mobile_write

Panelde Kullanım amacı olarak Mobile app (Mobil uygulama) seçilen anahtar bu ikiliyi birlikte taşır.

Uygulama kanalı bir alan adına sahip değildir; her zaman anahtar ister. Bir WebView içinden Origin gönderilse bile uygulama kanalı başlığı kanıt saymaz. Uygulama kanalı için tarayıcı kökeni CORS düzeyinde de reddedilir.

3. Amaca özel sunucu anahtarları

İki uç, anahtarı her zaman ister (başlığın varlığı farketmez), çünkü her zaman bir sunucu çağırır:

Uç	Kapsam	Panelde kullanım amacı
GET /public/sites/:siteKey/ssr/enrichments	ssr_read	Server-side rendering (Sunucu taraflı render)
POST /public/sites/:siteKey/contacts/consent	newsletter_subscribe	Consent sync (İzin senkronizasyonu)

Bu kapsamlar mobil çifti ile aynı torbada değildir ve bilinçlidir. Sunucu render anahtarı uygulama sunucunuzda yaşar; dağıtım hattınızdan, CI günlüklerinizden ve imajlardan geçer. Sızan bir ssr_read anahtarı hiçbir şey yazamaz ve iptali mobil uygulamanızı durdurmaz. newsletter_subscribe ise yalnızca bir adresin pazarlama iznini yazar, hiçbir şeyi geri okuyamaz.

Bir anahtarın bir kapsamı başka bir uca taşıması mümkün değildir: ssr_read anahtarıyla GET /config çağrısı 403 döner.

API anahtarı oluşturma

Channels → Channel Overview → Channel Key kartındaki API keys satırından Manage ile ya da Channels listesinde kanalın satırındaki ⋮ menüsünden API keys (API anahtarları) açılır. Purpose (Kullanım amacı) seçilir: Mobile app, Server-side rendering veya Consent sync. Bir ad verin (Mağaza SSR, iOS uygulaması). Ayrıntı ve roller: API Anahtarları.

• Anahtar swpk_live_ ile başlar ve yalnızca bir kez gösterilir. Selwise yalnızca SHA-256 özetini saklar, kaybederseniz geri getirilemez.
• Rotate (Döndür) yeni bir anahtar üretir ve eskisini aynı anda iptal eder; kapsamlar korunur.
• Revoke (İptal et) anahtarı anında geçersiz kılar. Onu kullanan her şey 403 almaya başlar.
• Listede her anahtarın Last used (son kullanım) zamanı görünür; bir anahtarın hâlâ kullanılıp kullanılmadığını buradan anlarsınız.

Anahtarı tarayıcıya, mobil uygulama paketine (SSR ve izin anahtarları için), bir NEXT_PUBLIC_ değişkenine veya herkese açık bir depoya koymayın. Mobil SDK anahtarı uygulamanın içinde durur; bu yüzden salt mobile_read/mobile_write yetkisinden fazlasını taşımaz.

Doğrulamasız uçlar

Bazı uçlar yalnızca siteKey ister: kanalın var olması ve doğrulanmış olması yeter, Origin ya da anahtar aranmaz. Hepsi analitik veya abonelik kaydı yazar ve hiçbiri veri okutmaz:

Uç	Ne yazar
POST .../events/batch	Olay kaydı
POST .../metrics	İstemci sağlık sayaçları (yalnızca günlüğe yazılır)
POST .../search/log, .../search/click, .../search/zero-results	Arama analitiği
POST .../recommendations/track/event, .../track/behavior	Öneri analitiği
POST /public/experiments/track, POST /public/experiments/track-event (siteKey sorgu parametresi)	Deney sayaçları
GET ve POST .../unsubscribe, POST .../push/subscribe, .../push/unsubscribe	E-posta bağlantısından çıkış ve tarayıcı bildirim aboneliği

Bu yüzden bu uçlara sunucudan istek atarken ne başlık ne anahtar gerekir. Ama bu bir davet değil: sahte olay göndermek sizin ölçümünüzü bozar. Sunucudan olay ve sipariş gönderen entegrasyonlarda yine de kanal API anahtarını kullanan uçları tercih edin; sipariş ucu buna dahildir.

Alan adını elle denetleyen uçlar

POST .../users/identify, POST .../users/traits, POST .../consent ve DELETE .../consent yukarıdaki iki yoldan birini ister (başlık varsa alan adı, yoksa mobile_write anahtarı). Diğer uçlar gibi bunlar da kanalın doğrulanmış takma adlarını kabul eder. Uygulama kanalında başlık olsa da her zaman API anahtarı istenir.

Reddedilme nedenleri

Hata gövdesinin biçimi için Hatalar ve Sınırlar sayfasına bakın. Erişim denetimi şu sırayla çalışır ve her adımın kendi durum kodu vardır:

Adım	Durum	message	Anlamı
Anahtar var mı	404	Site not found	Site anahtarı yanlış ya da kanal silinmiş
Doğrulanmış mı	403	Site not verified	Kanalın alan adı doğrulanmamış. Bkz. Alan Adı Doğrulama
Köken	403	Origin 'x' is not authorized for site 'y'	Başlıktaki host kanalın alan adlarından biri değil; ileti kabul edilen tüm alan adlarını sayar
Anahtar	403	Invalid API key or insufficient scope	Başlık yok, anahtar iptal edilmiş ya da kapsamı yetmiyor
Anahtar (SSR, izin)	401	... requires an API key in the x-selwise-api-key header	Başlık hiç gönderilmemiş
Hesap	403	Delivery is switched off for this account. ya da This account is closed.	Hesabın teslimatı elle kapatılmış ya da sözleşme iptal edilmiş
Modül	402	kod MODULE_NOT_ENTITLED	Hesabın sözleşmesinde bu modül yok

Hesap kontrolü bilinçli olarak gevşektir: süresi dolmuş, askıya alınmış ya da yenilenmeyi bekleyen bir sözleşme vitrini durdurmaz. Yalnızca bir süper yöneticinin teslimatı elle kapatması veya sözleşmenin iptali durdurur. Kontrol kanal başına beş dakika önbelleğe alındığı için değişiklik bu pencere içinde yansır.

Doğrulamasız uçlarda ve identify, traits, consent için bilinmeyen ya da doğrulanmamış site anahtarının sonucu uca göre değişir:

Uç	Bilinmeyen anahtar	Doğrulanmamış kanal
events/batch, search/log, search/click, search/zero-results, consent	200 ve success: false	200 ve success: false
recommendations/track/*	200 ve success: false (error: "Site not found")	Yazılır
identify, traits	404 ve kod SITE_KEY_NOT_FOUND	403 ve kod SITE_NOT_VERIFIED
/public/experiments/*	403 (Organization not found)	403 (Site not verified)

Yani events/batch veya search/log çağrısının HTTP durumu 200 olsa da success: false dönebilir. Ağ sekmesinde yalnızca durum koduna bakmayın, gövdeye de bakın.

CORS

Tarayıcıdan yapılan çağrılar için API, Origin başlığını kanalın doğrulanmış alan adları ve takma adlarıyla karşılaştırır ve yalnızca onlara CORS izni verir. Doğrulanmamış kanal, bilinmeyen site anahtarı ve uygulama kanalı için tarayıcı kökeni reddedilir. İzin verilen başlıklar Content-Type, Authorization, X-Requested-With, X-CSRF-Token ve X-Impersonation-Token'dır. x-selwise-api-key bu listede yoktur: anahtarlı çağrılar tarayıcıdan değil sunucudan yapılır ve yapılmalıdır.

Origin göndermeyen istekler (sunucu, curl, mobil) CORS kontrolüne hiç girmez.

CSRF

/public/ altındaki uçlar çerez kullanmaz; bu yüzden CSRF belirteci istemez.

Sırada ne var

• Public API — tüm uçların listesi
• Hatalar ve Sınırlar — hata gövdesi, hız sınırları, yeniden deneme
• Sunucu Taraflı Render API — ssr_read anahtarının kullanıldığı uç