API anahtarları ve kapsamlar

Sursa API’ye yapılan her istek, kuruluşunuzun bir API anahtarıyla yapılır. Anahtar bir kişiye değil kuruluşa aittir: onu oluşturan çalışan ayrıldığında da çalışmaya devam eder ve neler yapabileceği anahtarın kendisinde ayarlanır.

Bir anahtarın yapmasına izin verilenler

Anahtarın üç ayarı, onunla yapılan bir isteğin neyi görebileceğini ve değiştirebileceğini belirler. Her ayar yalnızca diğerlerini daraltır.

Ayar	Neyi denetler
Role (rol)	`admin`, `editor`, `verifier` ya da `viewer`: kişilerin sahip olduğu rollerin aynısı. Anahtar, bu role sahip bir kullanıcının yapabildiklerini yapabilir.
Scopes (kapsamlar)	Anahtarın API’nin hangi bölümlerini çağırabileceği, örneğin `cards:read` ya da `webhooks:manage`. Anahtar kapsamları sayfasına bakın.
Data profile (veri profili)	İsteğe bağlı. Anahtarı, bu profile sahip bir kullanıcı gibi, profilin izin verdiği bilgi kategorileriyle sınırlar.

Bir anahtar ayrıca bazı koleksiyonlarla sınırlanabilir ve bir sona erme tarihi alabilir. Bu sınırların dışındaki bir istek başarısız olur: eksik bir kapsam api_keys.scope koduyla 403 döndürür, anahtarın erişemediği bir nesne ise tıpkı hiç yokmuş gibi 404 döndürür.

Her entegrasyona, ihtiyaç duyduğu en dar rol ve kapsamlarla kendi anahtarını verin. Yalnızca belge yazan bir senkronizasyon işinin admin rolüne, bir raporlama işinin de yazma kapsamlarına ihtiyacı yoktur.

Anahtar oluşturma

Kuruluş yöneticisi anahtarları Sursa’da Administration → API keys (yönetim → API anahtarları) bölümünde ya da admin rolüne sahip bir anahtar veya oturumla POST /v1/api-keys çağrısıyla oluşturur:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Yanıt, anahtarın değerini key alanında içerir. Bu değer bir kez gösterilir: Sursa yalnızca değerin özetini (hash) saklar ve değeri bir daha gösteremez. Bir anahtar kb_ ve ardından gelen 43 karakterden oluşur; anahtarları birbirinden ayırt edebilmeniz için ilk karakterleri (prefix) anahtar listesinde gösterilir.

scopes gönderilmezse anahtar rolünün kapsamlarını alır. Anahtarı daha da daraltmak için scopes gönderin. expires_at gönderilmezse anahtarın süresi dolmaz.

Anahtarları gizli tutma

Anahtarları kaynak kodunda değil, bir gizli değer yöneticisinde ya da hizmetinizin ortam değişkenlerinde saklayın.
Anahtarları yalnızca kendi sunucularınızdan kullanın. Sursa tarayıcılardan gelen istekleri kabul eder (CORS açıktır), ancak bir web sayfasındaki anahtarı o sayfayı açan herkes görebilir.
Anahtarı hiçbir zaman URL içinde göndermeyin. Yalnızca Authorization başlığında gönderin.
Bir anahtar sızarsa hemen iptal edin ve yeni bir anahtar oluşturun.

Anahtarı kontrol etme

GET /v1/me anahtarı, rolünü, etkin kapsamlarını, veri profilini, sona erme tarihini ve hız sınırını döndürür. Kapsamları ne olursa olsun her geçerli anahtarla çalışır; bu yüzden onu entegrasyonunuzun bağlantı testi olarak ve bir 403 yanıtını incelerken kullanın.

Anahtarı yenileme

Yenileme, entegrasyonu durdurmadan bir anahtarın yerine yenisini koyar. En hızlı yol anahtarı yenilemektir: POST /v1/api-keys/{key_id}/roll aynı anahtar için aynı rol, kapsamlar, koleksiyonlar ve sona erme tarihiyle yeni bir değer verir. Önceki değer overlap_hours boyunca (varsayılan olarak 24 saat, en fazla 168) çalışmaya devam eder; böylece bu sürede yeni değeri dağıtabilirsiniz. POST /v1/api-keys/{key_id}/revoke-previous örtüşme süresini erken bitirir.

Bunun yerine bir anahtarın yerine farklı bir anahtar koymak için:

Aynı rol, kapsamlar ve veri profiliyle yeni bir anahtar oluşturun.
Yeni anahtarı entegrasyonunuza dağıtın.
Eski anahtar artık kullanılmayana kadar onu Administration → API keys bölümünde (ya da GET /v1/api-keys yanıtındaki last_used alanında) izleyin.
Eski anahtarı iptal edin.

Anahtarlara bir sona erme tarihi koyun ve onları bu tarihten önce yenileyin. Sursa, bir anahtarın süresi dolmadan önce kuruluşun yöneticilerini uyarır; süresi dolmuş bir anahtar api_keys.expired koduyla 401 döndürür.

Anahtarı iptal etme

Bir anahtarı Administration → API keys bölümünde ya da DELETE /v1/api-keys/{key_id} ile iptal edin. İptal, birkaç saniye içinde tüm API sunucularında geçerli olur. İptal edilmiş bir anahtarla yapılan istekler auth.not_authenticated koduyla 401 döndürür.

Özel kaynak anahtarları

Bir özel kaynağın kendine özgü bir anahtar türü vardır. Bu anahtar kbsrc_ ile başlar, yalnızca o tek kaynağa belge yazabilir ve hiçbir şeyi okuyamaz ya da arayamaz. Zapier gibi bir entegrasyon platformuna verilebilecek en güvenli anahtardır. Bu anahtarı kaynak sayfasındaki API keys bölümünde ya da POST /v1/sources/{source_id}/push-keys ile oluşturun.

Anahtarlar kullanılamadığında

API anahtarları kuruluşun planının bir parçasıdır. Plan bunları içermiyorsa hem anahtar oluşturma hem de anahtarla yapılan her istek api_keys.feature_disabled koduyla 403 döndürür.