Anahtar kapsamları

Kapsam, bir anahtarın çağırabileceği API bölümünü adlandırır. API başvurusundaki her uç nokta, ihtiyaç duyduğu tek kapsamı belirtir. Bu kapsama sahip olmayan bir anahtarla yapılan istek, herhangi bir şey okunmadan ya da değiştirilmeden önce api_keys.scope koduyla 403 yanıtı alarak reddedilir.

Kapsamlar, bir anahtarın hangi işlemleri çağırabileceğini belirler. Bu işlemlerin hangi nesnelere ulaşacağını ise yine anahtarın rolü, veri profili ve koleksiyonları belirler: cards:write kapsamına ve viewer rolüne sahip bir anahtar kartları değiştiremez, tek bir koleksiyonla sınırlı bir anahtar da diğer koleksiyonlara erişemez.

Kapsamlar

Kapsam	İzin verdiği
`cards:read`	Kartları, koleksiyonları ve klasörleri okuma.
`cards:write`	Kart, koleksiyon ve klasör oluşturma, değiştirme ve silme.
`search`	Bilgi tabanında arama (`POST /v1/search`).
`ask`	Asistana soru sorma (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Kuruluşun özel kaynaklarına yazma: senkronizasyonlar, toplu gönderimler ve silinenler; ayrıca bunların durumunu okuma. Kaynak ve kaynak anahtarları oluşturmak için `admin` gerekir.
`webhooks:manage`	Webhook’ları yönetme ve olay beslemesini okuma (`GET /v1/webhook-events`). İkisi için de ayrıca `admin` rolü gerekir.
`users:read`	Kullanıcıları ve grupları okuma.
`users:write`	Kullanıcıları ve grupları değiştirme.
`analytics:read`	Analitik verilerini okuma.
`audit:read`	Denetim kaydını okuma.
`finance:read`	Finansal raporları, faturaları ve ödemeleri okuma.
`catalog:read`	Hizmet kataloğunu okuma.
`files:read`	Dışa aktarılan yanıtlar gibi üretilmiş dosyaları okuma.
`files:write`	Üretilmiş dosyaları değiştirme ve silme.
`permissions:manage`	Nesnelerde izin atama ve izinleri kaldırma.
`admin`	Kuruluşun ayarları ve API anahtarları. `admin` kapsamına sahip bir anahtar diğer tüm kapsamlara da sahiptir.

Arama ve soru sorma, niteliği bakımından okuma işlemleridir: yalnızca okuma yapabilen bir anahtar da arama yapabilir ve soru sorabilir.

Kapsamları seçme

Bir entegrasyona yalnızca kullandığı kapsamları verin, fazlasını vermeyin:

Entegrasyon	Kapsamlar
Sohbet aracında soru-cevap botu	`search`, `ask`
Belge sisteminizden içe aktarma	`cards:write` (kart API’si) ya da `import:write` (özel kaynak)
Veri ambarına aktarma	`cards:read`, `users:read` ve olay beslemesi için `webhooks:manage`
İnsan kaynakları sisteminizden kullanıcı hesapları oluşturma	`users:write`

Kapsam listesini anahtarı oluştururken gönderin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

Eski kapsamlar

Kapsamlar bölünmeden önce oluşturulmuş anahtarlar çalışmaya devam eder. Bu anahtarların read, write ve admin kapsamları şu kümelere karşılık gelir:

Eski kapsam	Anlamı
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	`read` kapsamındaki her şey ve ek olarak `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	tüm kapsamlar

Açıkça kapsam belirtilmeden oluşturulan bir anahtar kapsamlarını rolünden alır: admin rolü admin kapsamını, editor ve verifier rolleri write kapsamını, viewer rolü read kapsamını alır.

Bir anahtarın kapsamlarını görme

GET /v1/me, isteği yapan anahtarın kapsamları ne olursa olsun bu anahtarın kapsamlarını döndürür. Açık kapsamlar belirtilmeden oluşturulmuş bir anahtar için bunlar, rolünün read ve write gibi önceki kapsamlarıdır; ne anlama geldiklerini yukarıdaki tablo gösterir. Bir işlem api_keys.scope koduyla başarısız olduğunda error.message alanı eksik olan kapsamı belirtir.