Kimlik doğrulama ve API anahtarları

Veri API’nin tüm uçları firma API anahtarıyla çalışır. Anahtar her istekte Authorization başlığında gönderilir:

Authorization: Bearer rz_live_xxx

Konsol oturumu (çerez) bu uçlarda geçmez; konsol kullanıcıları için olan uçlar da API anahtarını kabul etmez.

Anahtar türleri

Tür	Biçim	Nerede	Ne yapabilir
Gizli	rz_live_ + 32 karakter	Yalnız sunucunuzda	Seçtiğiniz kapsamlardaki tüm Veri API uçları
Yayınlanabilir	rz_pub_ + 32 karakter	Tarayıcıda, sitenizde	Yalnız calls:request: gömülebilir butonun uçları, yalnız izinli alan adlarından

Yayınlanabilir anahtar buton dışındaki uçlarda 403 publishable_key_not_allowed alır ve tek başına arama başlatamaz; her istek sunucunuzun ürettiği tek kullanımlık bir token ister. Buton →

Anahtar oluşturma

1. Ayarlar → API anahtarları → Yeni anahtar (yönetici ve üstü; paket: Veri API ya da Asistan arasın butonu).
2. Anahtar türü: Gizli (sunucunuzda) ya da Herkese açık (buton). Yayınlanabilir anahtarda izinli alan adlarını her satıra bir tane yazın (https://www.example.com; yol ve sorgu yok; http yalnız localhost ve *.test için).
3. Gizli anahtar için yetkileri (kapsamları) seçin. En az bir kapsam gerekir.
4. Anahtar oluştur. Anahtar yalnız bir kez gösterilir: hemen kopyalayıp güvenli bir yere kaydedin.

Anahtar veritabanında düz olarak durmaz; yalnız SHA-256 özeti ve son dört hanesi saklanır. Kaybederseniz iptal edip yenisini oluşturun. Her sistem için ayrı anahtar açmanız önerilir: böylece tek tek iptal edebilirsiniz. Listede her anahtarın son kullanım zamanı görünür. Paketinizin API anahtarı limiti etkin (iptal edilmemiş) gizli ve yayınlanabilir anahtarları birlikte sayar.

İptal et anında geçerlidir: anahtarı kullanan sistemler hemen erişimi kaybeder.

Kapsamlar

Kapsam	İzin verdiği uçlar
ingest:catalog	PUT /api/v1/catalog/products, DELETE /api/v1/catalog/products/{item_ref}, PUT /api/v1/catalog/categories, DELETE /api/v1/catalog/categories/{kategori_id}
ingest:orders	PUT /api/v1/orders
ingest:kb	PUT /api/v1/kb/articles
ingest:carts	PUT /api/v1/sepetler, DELETE /api/v1/sepetler/{dis_id}
read:carts	GET /api/v1/sepetler
ingest:customers	PUT /api/v1/musteriler, DELETE /api/v1/musteriler/{dis_id}
read:requests	GET /api/v1/requests
calls:read	GET /api/v1/cagrilar, GET /api/v1/cagrilar/{call_id}, GET /api/v1/konular/istatistik, GET /api/v1/aramalar/{arama_id}
calls:read:transcript	GET /api/v1/cagrilar/{call_id} yanıtında transcript. calls:read’i de kapsar (anahtara otomatik eklenir)
calls:write	POST /api/v1/aramalar, GET /api/v1/aramalar/{arama_id}, GET /api/v1/amaclar, POST /api/v1/buton-token
webhooks	Ayrılmış; bugün bu kapsamla açılan bir uç yok
calls:request	Yalnız yayınlanabilir anahtarda; butonun tarayıcı uçları

GET /api/v1/me kapsam istemez; anahtarın geçerli olduğunu ve kapsamlarını döner. Bağlantı testi için kullanın:

curl -s "$RZ_API/api/v1/me" -H "Authorization: Bearer $RZ_KEY"
# {"org": "firma", "key_name": "Site entegrasyonu", "scopes": ["ingest:catalog", "ingest:orders"]}

Paket özellikleri

Uçlar firmanızın paketine bağlıdır. Paketinizde kapalı bir özelliğin uçları 404 not_found döner (uç yokmuş gibi):

Uçlar	Gereken özellik
me, catalog/*, kb/articles, orders	yok — her pakette açık
requests, cagrilar	Veri API
konular/istatistik	Veri API + Konu analitiği
aramalar, amaclar	Veri API + Giden arama
sepetler, musteriler	Veri API + Sepetler
buton-token	Asistan arasın butonu (Giden arama da açık olmalı)

Anahtar güvenliği

Gizli anahtarı asla tarayıcıya, mobil uygulamaya ya da herkese açık bir depoya koymayın. Anahtar sızdıysa hemen iptal edin; Değişiklik Geçmişi’nde anahtarın kim tarafından, hangi kapsamlarla oluşturulduğu ve iptal edildiği görünür.