API Anahtarları

API anahtarı, tarayıcıdan gelmeyen bir çağrının (mobil uygulama, sunucu taraflı render, kendi arka ucunuz) kanala kendini tanıtma yoludur. Tarayıcı isteği kanalın alan adına karşı kontrol edilir; sunucu isteğinin kontrol edilecek bir Origin'i yoktur, bu yüzden bir anahtar sunar.

Panelde nerede

İki giriş vardır, ikisi de aynı pencereyi (API keys) açar:

• Channels → Channel Overview → Channel Key kartı → API keys satırındaki Manage (Yönet). Satır kaç aktif anahtar olduğunu söyler.
• Channels listesinde bir satırın ⋮ menüsü → API keys.

Anahtarları oluşturmak, yenilemek ve iptal etmek admin rolünün yetkisidir (site:update); marketing rolü listeyi görür ama değiştiremez. Uygulama kanalında Setup bölümünün ilk adımı bu pencereyi açar.

Anahtar nasıl görünür

Anahtar swpk_live_ ve ardından 64 onaltılık karakterden oluşur. Selwise yalnızca bir SHA-256 özetini saklar; bu yüzden anahtarın tamamı yalnızca oluşturma ve yenileme anında, bir kez gösterilir ("Copy this key now"). Listede yalnızca ilk 14 karakter (swpk_live_ab12) ve amacı görünür. Pencere kapanınca anahtar ekrandan silinir. Kaybettiyseniz geri getirilemez — anahtarı Rotate ile yenileyin.

Amaçlar

Pencere bir yetki listesi değil bir amaç seçtirir; doğru yetki çiftini elle kurmak zorunda kalmazsınız ve yanlışını kuramazsınız.

Amaç	Verilen yetki	Ne için
Mobile app (Mobil uygulama)	mobile_read + mobile_write	@selwise/react-native SDK'sı. Okuma ve yazma birlikte gerekir: SDK olay ve sipariş de gönderir
Server-side rendering (Sunucu taraflı render)	yalnızca ssr_read	Uygulama sunucunuzdan zenginleştirme içeriğini kendi şablonlarınıza basmak. Salt okunurdur; hiçbir tarayıcıya vermeyin — bkz. SSR API
Consent sync (İzin senkronizasyonu)	yalnızca newsletter_subscribe	Kendi arka ucunuzdan ya da CRM'inizden, ödeme dışında alınmış bir pazarlama iznini (açık rıza ya da çekilme) POST /api/v1/public/sites/SITE_KEY/contacts/consent ile Selwise'e yazmak. Yazma-yalnızdır, geri okuyamaz
Order status sync (Sipariş durumu senkronu)	yalnızca orders_write	Sipariş sisteminizden, verilmiş bir siparişin iptalini, iadesini ya da geri gönderimini POST /api/v1/public/sites/SITE_KEY/orders/ORDER_ID/status ile bildirmek; Selwise böylece elde kalmayan ciroyu saymayı bırakır — bkz. Sipariş API'si. Yazma-yalnızdır

SSR, izin ve sipariş durumu anahtarları mobil çiftle bilerek birleştirilmez: sunucu anahtarı sizin dağıtım hattınızdan, CI günlüklerinizden ve konteyner imajlarınızdan geçer; sızması hiçbir şey yazamamalı, bir tanesini iptal etmek de mobil uygulamayı düşürmemelidir.

Anahtar oluşturmak

Create a key bölümünde:

Alan	Kural
Name (Ad)	Zorunlu, en fazla 120 karakter. Sonra tanıyacağınız bir ad: "iOS app", "Storefront SSR"
Purpose (Amaç)	Yukarıdaki dört seçenek. Seçenek değişince altında ne işe yaradığı yazar

Create key (Anahtar oluştur) sonrası Copy this key now kutusu anahtarı gösterir; Copy key (Anahtarı kopyala) panoya yazar ve tarayıcı reddederse "select the key and copy it by hand" der.

API karşılığı: POST /api/v1/channels/CHANNEL_ID/public-api-keys gövde name (zorunlu) ve scopes (isteğe bağlı; boşsa mobile_read + mobile_write). İzinli yetkiler: mobile_read, mobile_write, ssr_read, newsletter_subscribe, orders_write.

Nasıl sunulur

Anahtar her istekte başlıkta gider:

x-selwise-api-key: swpk_live_...

Hangi yetkinin gerektiği isteğin HTTP yönteminden türetilir:

İstek	Gereken yetki
GET	mobile_read
POST, PUT, DELETE…	mobile_write
SSR uçları	ssr_read
contacts/consent	newsletter_subscribe
orders/ORDER_ID/status	orders_write

Bunun bir sonucu: öneri ürünleri uç noktası bir POST'tur (bağlam gövdesi alır), bu yüzden yalnızca okuma yetkisi olan bir anahtar orada 403 alır ve ekranda başka açıklama yoktur. Mobil anahtar her zaman iki yetkiyi birden taşımalıdır.

Listeyi okumak

Her satırda: ad, anahtarın ilk 14 karakteri ve amacı, Last used (Son kullanım — ya da Never used, hiç kullanılmadı) ve Rotate / Revoke düğmeleri. İptal edilmiş anahtarlar Revoked (İptal edildi) olarak listede kalır.

• Rotate (Döndür): aynı ad ve yetkilerle yeni bir anahtar üretir, eskisi anında iptal edilir. Yeni anahtar bir kez gösterilir; uygulamanızı ve sunucunuzu güncellemeden yenilemeyin.
• Revoke (İptal et): onaydan sonra anahtarı kullanan her şey hemen çalışmayı bırakır ("Anything still using it stops working immediately"). Geri alınamaz.

Hata kodları

Durum	Neden
403 Invalid API key or insufficient scope	Anahtar yanlış, iptal edilmiş, bu kanala ait değil ya da gereken yetkiyi taşımıyor (örneğin POST çağrısında yalnızca mobile_read)
401 … requires an API key in the x-selwise-api-key header	SSR, izin ya da sipariş durumu ucuna başlıksız çağrı
Uygulama kanalından her istek 403	Anahtar hiç yok ya da başlık gönderilmiyor — SDK apiKey seçeneği boş
403 Site not verified	Anahtar doğru ama bir web kanalının alan adı doğrulanmamış — bkz. Domain Doğrulama
Anahtar oluşturma API_KEY_NAME_REQUIRED	Ad boş

Güvenlik

Bu anahtarlar gizlidir (kanal anahtarından farklı olarak) ve sayfa kaynağına yazılmaz. Bir anahtarın sızdığından şüpheleniyorsanız Rotate edin ya da Revoke edip yenisini oluşturun.