Eski Genel API - Living Security Platform

Bu kılavuz, bir API erişim anahtarını bearer belirteci ile değiştiren mevcut /api/v1 entegrasyonlarını kapsar. Bunların kimlik bilgileri ve istek biçimi, /v1 Genel API’den farklıdır. Yeni bir entegrasyon için API hızlı başlangıç kılavuzu ve Kimlik Doğrulama sayfalarıyla başlayın. Yeni /v1 API, hizmet hesabı API anahtarlarını veya OAuth erişim belirteçlerini kullanır.

Başlamadan Önce

Şunlara ihtiyacınız vardır:

API erişim anahtarı yönetimine izin veren Living Security erişimi
Ayarlar → Access Keys altında oluşturulmuş bir API erişim anahtarı
Kimlik bilgisi oluşturulduğunda yalnızca bir kez gösterilen erişim anahtarı sırrı
Genel API kimlik bilgilerinizle birlikte Living Security tarafından sağlanan API düzenleyici (issuer) kimliği
Entegre ettiğiniz kuruluşun bölgesel temel URL’si
Sunucu tarafı bir çalışma ortamı ve bir sır yöneticisi

Erişim anahtarı sırları; tarayıcı koduna, mobil uygulamalara, kaynak kod denetimine, istemci tarafı ortam değişkenlerine, taleplere veya paylaşılan günlüklere yerleştirilmemelidir.

Access Keys iletişim kutusu yalnızca bir kez gösterilen sırrı gösterir, ancak API düzenleyici kimliğini göstermez. Living Security, Genel API kimlik bilgilerinizle birlikte düzenleyici kimliğini sağlamadıysa bunu Living Security Destek ekibinden talep edin. Düzenleyici kimliği, erişim anahtarı kimliği veya kuruluş kimliği değildir.

Bölgesel Ana Bilgisayarlar

Eski sözleşme, aşağıdaki bölgesel /api/v1 üretim ana bilgisayarlarını kullanır:

Bölge	Temel URL
ABD	`https://api.us-east-1.livingsecurity.ai/api/v1`
AB	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Living Security kuruluşuna atanan bölgeyi kullanın. Bir yetkilendirme veya erişilebilirlik hatasını aşmak için bölge değiştirmeyin.

Eski Kaynaklar

Kaynak	Desteklenen işlemler
İnsanlar	Kuruluştaki kişileri arama ve bir kişinin üyeliğini alma
API erişim anahtarları	API erişim anahtarlarını oluşturma, listeleme, döndürme ve iptal etme

İşlem, parametre, istek, yanıt ve şema listesinin tamamı için Developers → Public API Reference bölümünü kullanın. Bir işlem orada yer almıyorsa, şu anda Genel API’nin parçası değildir.

Kimlik Doğrulama

Genel API erişimi iki aşamadan oluşur:

Gizli erişim anahtarını ve API düzenleyici kimliğini, kısa ömürlü bir bearer belirteci ve kuruluş kimliği ile değiştirin.
Her API isteğinde bearer belirtecini ve kuruluş kimliğini gönderin.

Gerekli istek üst bilgileri şunlardır:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

Kuruluş üst bilgisi, erişim anahtarı değişiminden dönen kuruluş olmalıdır. Bir anahtar, rastgele bir kuruluş kimliğine erişim yetkisi vermez.

TypeScript SDK

Güncel ana sürümü yükleyin:

npm install @livingsecurity/sdk@^1

Ardından anahtarı değiştirin ve SDK’yı yapılandırın:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

Bir AB kuruluşu için AB temel URL’sini kullanın. SDK değişimi, sunucu tarafı Node.js çalışma ortamları için tasarlanmıştır.

Doğrudan REST İsteği

Değişimi SDK dışında gerçekleştirirseniz, her istekte bearer belirtecini ve kuruluş kimliğini gönderin:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

Bearer belirteçlerinin ömrü kısadır. Bir bearer belirtecini kalıcı bir kimlik bilgisi olarak saklamak yerine, yeni bir belirteç almak için erişim anahtarını yeniden değiştirin.

Erişim Anahtarı Yaşam Döngüsü

Anahtarları, sahibi olan entegrasyonun veya otomasyonun adıyla adlandırın.
Erişim anahtarı formunda sunulan en az ayrıcalıklı kapsamları seçin.
Bir kez gösterilen sırrı hemen saklayın; oluşturma veya döndürme işleminden sonra yeniden alınamaz.
Bir anahtarı Ayarlar → Access Keys üzerinden döndürün ve eski kimlik bilgisini iptal etmeden önce yenisini dağıtın.
Artık kullanılmayan veya sırrı açığa çıkmış olabilecek anahtarları iptal edin.
Kuruluşunuzda bu anahtar türü mevcutsa, insan olmayan entegrasyonlar için hizmet hesabı anahtarlarını kullanın.

Sayfalama

Kişi araması limit, cursor, offset ve includeTotal parametrelerini destekler. Sıralı gezinme için önceki yanıtta dönen imleci tercih edin.

limit varsayılan olarak 50’dir ve 1–100 değerlerini kabul eder.
cursor önceki bir yanıttan devam eder.
offset belirli sayıda kaydı atlar ve varsayılan değeri 0’dır.
includeTotal=true filtrelenmiş kesin bir sayı ister; sayı gerekmiyorsa bunu atlayın.

Uç noktanın döndürdüğü pagination nesnesini okuyun. Sonraki sayfayı alınan satır sayısından hesaplamayın veya bağımsız olarak sayfalanan istekleri birleştirip kısmi sonuçları kendiniz sıralamayın.

Hatalar

Belgelenmiş JSON hataları şu genel yapıyı kullanır:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message bir dize veya doğrulama iletilerinden oluşan bir dizi olabilir.

Durum	Anlamı	Yanıt
`400`	Geçersiz parametreler veya istek gövdesi	Belirtilen doğrulama hatalarını düzeltin
`401`	Bearer belirteci eksik, geçersiz veya süresi dolmuş	Erişim anahtarını yeniden değiştirin ve bir kez yeniden deneyin
`403`	Kimlik bilgisinin izni veya kuruluş erişimi yok	Anahtar kapsamlarını ve kuruluş bağlamını kontrol edin
`404`	Kaynak, yetkilendirilmiş kuruluşta mevcut değil	Kaynak kimliğini ve kuruluşu doğrulayın
`408`	İstek zaman aşımına uğradı	Sınırlı üstel geri çekilme ile yeniden deneyin
`429`	İstek sınırına ulaşıldı	`Retry-After` varsa en az o süre kadar bekleyin
`5xx`	Geçici hizmet hatası	Güvenli okuma işlemlerini sınırlı üstel geri çekilme ile yeniden deneyin

Derlenmiş sözleşme şu anda tek bir evrensel sayısal istek sınırı yayımlamamakta veya her işlem için bir istek kimliği yanıt üst bilgisini garanti etmemektedir. Destek talep ederken UTC saatini, yöntemi, yolu, durumu ve temizlenmiş yanıt gövdesini kaydedin. İşlem açıkça idempotentliği belgelemediği sürece oluşturma, döndürme, iptal etme veya silme işlemlerini otomatik olarak yeniden denemeyin. Belirsiz bir ağ hatasından sonra kaynağın güncel durumunu kontrol edin.

Uyumluluk ve Kullanımdan Kaldırma

V1 varsayılan olarak eklemeli biçimde gelişir. İstemciler bilinmeyen yanıt alanlarını yok saymalıdır. Geriye dönük uyumsuz bir değişiklik, belgelenmiş bir geçiş yolu gerektirir; kullanımdan kaldırılan işlemler, geçiş döneminde nedenleri, varsa yerine geçen işlem ve kullanımdan kalkış tarihiyle birlikte referansta kalır. SDK’yı uyumlu bir ana sürüme sabitleyin ve yükseltmeden önce sürüm notlarını inceleyin. Şema için doğru kaynak olarak, birinci taraf uygulama istemcilerini değil, oluşturulan Public API Reference’ı esas alın.

Genel API, MCP ve Web Uygulaması

Yüzey	Kullanım amacı	Uyumluluk modeli
Genel API	Müşteri sistemleri, iş ortakları ve harici otomasyon	Kararlı, sürümlü kaynaklar
MCP	İzin tabanlı yapay zekâ aracı etkileşimleri	Araç sözleşmeleri ve kompakt yapılandırılmış çıktılar
Web uygulaması	Living Security ürünündeki insan iş akışları	Arayüzle birlikte gelişebilen uygulamaya ait sözleşmeler

Bir yapay zekâ aracını Living Security’ye bağlamak için MCP Entegrasyonu sayfasına bakın.

Yardım Alın

Aşağıdaki bilgilerle Living Security Destek ekibiyle iletişime geçin:

Kuruluş ve bölge
Kullanıldıysa SDK adı ve sürümü
UTC zaman damgası, yöntem ve yol
HTTP durumu ve temizlenmiş hata gövdesi

Erişim anahtarı sırlarını, bearer belirteçlerini veya özel müşteri verilerini kesinlikle eklemeyin.

İlgili Konular

API Erişim Anahtarları

API kimlik bilgilerini oluşturun, döndürün ve iptal edin.

MCP Entegrasyonu

Desteklenen yapay zekâ araçlarını Model Context Protocol üzerinden bağlayın.

Genel API

Genel API Başvurusu

​Başlamadan Önce

​Bölgesel Ana Bilgisayarlar

​Eski Kaynaklar

​Kimlik Doğrulama

​TypeScript SDK

​Doğrudan REST İsteği

​Erişim Anahtarı Yaşam Döngüsü

​Sayfalama

​Hatalar

​Uyumluluk ve Kullanımdan Kaldırma

​Genel API, MCP ve Web Uygulaması

​Yardım Alın

​İlgili Konular

API Erişim Anahtarları

MCP Entegrasyonu

Başlamadan Önce

Bölgesel Ana Bilgisayarlar

Eski Kaynaklar

Kimlik Doğrulama

TypeScript SDK

Doğrudan REST İsteği

Erişim Anahtarı Yaşam Döngüsü

Sayfalama

Hatalar

Uyumluluk ve Kullanımdan Kaldırma

Genel API, MCP ve Web Uygulaması

Yardım Alın

İlgili Konular