Kimlik doğrulama

Sursa API’ye yapılan her istek, Authorization başlığında bir API anahtarı ya da bir uygulamanın OAuth erişim belirtecini taşır:

Authorization: Bearer kb_3f9c…

Anahtar kuruluşu tanımlar ve isteğin neyi görebileceğini ve değiştirebileceğini belirler: anahtarın rolü, kapsamları, veri profili ve koleksiyonları. API adresinde oturum ya da çerez yoktur. Her istek ayrı ayrı doğrulanır; bu yüzden aynı anahtarla istekleri paralel olarak ve birden fazla sunucudan gönderebilirsiniz.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Daha önceki entegrasyonlar anahtarı bunun yerine X-API-Key başlığında gönderebilir. Bu başlık hâlâ kabul edilir, ancak yeni kodda Authorization: Bearer kullanılmalıdır.

Kimlik bilgisi türleri

Kimlik bilgisi	Görünümü	Nerede çalışır
Kuruluş API anahtarı	`kb_…`	API’nin tüm uç noktalarında; anahtarın rolü, kapsamları, veri profili ve koleksiyonları sınırları içinde.
Özel kaynak anahtarı	`kbsrc_…`	Yalnızca kendi özel kaynağının gönderim (push) uç noktalarında (`/v1/push/sources/{source_id}/…`).
OAuth erişim belirteci	`kbat_…`	API başvurusundaki uç noktalarda; belirtecin kapsamları sınırları içinde. `POST /oauth/token` üzerinden yetkilendirme koduyla alınan belirteç, onay veren çalışan adına hareket eder; `client_credentials` belirteci ise bir API anahtarı gibi kuruluş adına hareket eder. 1 saat geçerlidir.

Hepsi aynı şekilde gönderilir. Özel kaynak anahtarıyla kendi kaynağının dışındaki hiçbir şey okunamaz, aranamaz ya da değiştirilemez; bu anahtarı, bir entegrasyon platformu gibi üçüncü bir tarafın sakladığı yerlerde kullanın.

Kimlik doğrulama hataları

Durum ve kod	Anlamı	Ne yapmalı
`401` `auth.not_authenticated`	Anahtar yok, yanlış yazılmış ya da iptal edilmiş.	Başlığı ve anahtarın değerini kontrol edin.
`401` `api_keys.expired`	Anahtarın sona erme tarihi geçmiş.	Yeni bir anahtar oluşturun ve eskisinin yerine koyun.
`401` `sources.push_key_invalid`	Özel kaynak anahtarı yanlış, iptal edilmiş ya da başka bir kaynağa ait.	Anahtarı ve yoldaki kaynak kimliğini kontrol edin.
`401` `oauth.token_expired`	OAuth erişim belirtecinin süresi dolmuş.	Yenileme belirteciyle yeni bir belirteç alın.
`403` `api_keys.scope`	Anahtarın bu işlem için kapsamı yok.	Kapsamı ekleyin ya da bu kapsama sahip bir anahtar kullanın.
`403` `api_keys.feature_disabled`	Kuruluşun planı API anahtarlarını içermiyor.	Kuruluşun yöneticisiyle iletişime geçin.
`403` `api_keys.ip_not_allowed`	İstek, anahtar için izin verilen adreslerin dışındaki bir adresten geliyor.	İzin verilen bir ağdan çağırın ya da anahtarın adreslerini değiştirin.
`403` `api_keys.mcp_only`	Kişisel bir MCP anahtarı `/mcp` uç noktasının dışında kullanılmış.	API için bir kuruluş API anahtarı kullanın.
`403` `oauth.operation_not_allowed`	İşlem herkese açık API’nin parçası değil, bu yüzden OAuth belirteci onu çağıramaz.	API başvurusundaki bir işlemi kullanın.
`403` `org.suspended`	Kuruluş askıya alınmış. Verileri korunur.	Kuruluşun yöneticisiyle iletişime geçin.

403, isteğin kimliğinin doğrulandığını ancak isteğe izin verilmediğini gösterir. Anahtarın erişemediği bir nesne, var olmayan bir nesne gibi 404 yanıtı verir; böylece bir anahtar erişiminin dışında ne olduğunu öğrenemez.

Bir veri profili adına çalışma

admin rolüne sahip bir anahtar, başka bir kişi grubunun ne göreceğini kontrol edebilir: X-View-As başlığı, isteği bir veri profili ve isteğe bağlı olarak bir rol adına çalıştırır.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Bu moddaki istekler yalnızca okuma yapar: her değişiklik isteği view_as.read_only koduyla 403 döndürür. OAuth belirteci ya da admin rolü olmayan bir anahtar X-View-As başlığını kullanamaz: istek view_as.admin_key_required koduyla 403 döndürür. Var olan hiçbir profili belirtmeyen bir başlık view_as.invalid_header koduyla 400 döndürür.

Tarayıcı uygulamaları

API her web kökeninden gelen isteklere izin verir (Access-Control-Allow-Origin: *) ve hiçbir zaman çerez kullanmaz; bu yüzden bir sayfa API’yi fetch ile çağırabilir. Bu durumda anahtar sayfanın içinde bulunur ve sayfayı kullanan herkes onu görebilir. API’yi tarayıcıdan yalnızca bu kullanıcılara göstermeyi kabul ettiğiniz bir anahtarla çağırın (örneğin herkese açık koleksiyonlarla sınırlı bir viewer anahtarı) ya da tarayıcı ile Sursa arasına kendi sunucunuzu koyun.

Yalnızca bir çalışanın yapabildikleri

Kuruluş API anahtarı bir kişi adına değil, kuruluş adına hareket eder. API’nin iki bölümü kişilere aittir; bu yüzden yalnızca bir çalışan adına hareket eden bir belirteçle kullanılabilir: Sursa’daki bir oturum ya da çalışanın onayıyla verilmiş bir OAuth erişim belirteci.

Sohbetler bir kişiye aittir. Kuruluş API anahtarına GET /v1/conversations yanıtında yalnızca anahtarın kendi başlattığı sohbetler gösterilir. Herkese açık API’de sohbet başlatan bir işlem yoktur; bu yüzden bir anahtar için liste normalde boştur ve çalışanların sohbetleri ona hiçbir zaman gösterilmez. Sohbet dışında POST /v1/ask ya da POST /v1/chat ile sorulan sorular, ask kapsamına sahip her anahtarla çalışır. Bir çalışanın sohbetlerini listelemek ve birinin geçmişini GET /v1/conversations/{conv_id} ile okumak için API’yi o çalışan adına bir OAuth belirteciyle çağırın. Belirteç yalnızca o çalışanın kendi sohbetlerine erişir; başka her sohbet conversations.not_found koduyla 404 döndürür.

Kartı yalnızca bir çalışan doğrular. Doğrulama, içeriği bir kişinin kontrol ettiğini teyit eder; bu yüzden POST /v1/cards/{card_id}/verification/verify ve POST /v1/cards/{card_id}/verify için bir oturum ya da kartı doğrulayabilecek bir çalışan adına verilmiş bir OAuth belirteci gerekir. Kuruluş API anahtarıyla ya da client_credentials belirteciyle bu işlemler cards.verify_user_account_required koduyla 400 döndürür. Önce olağan denetimler yapılır: anahtarın erişemediği bir kart 404, kartı doğrulama izni olmayan bir anahtar 403 yanıtı alır.