Régi Public API

Ez az útmutató a meglévő /api/v1 integrációkat tárgyalja, amelyek API-hozzáférési kulcsot cserélnek bearer tokenre. Hitelesítő adataik és kérésformátumuk eltér a /v1 Public API-tól. Új integrációhoz kezdje az API gyorsindítóval és a Hitelesítéssel. Az új /v1 API szolgáltatásfiók-API-kulcsokat vagy OAuth hozzáférési tokeneket használ.

Előkészületek

A következőkre van szüksége:

Living Security-hozzáférés, amely lehetővé teszi az API-hozzáférési kulcsok kezelését
A Beállítások → Access Keys menüpont alatt létrehozott API-hozzáférési kulcs
A hitelesítő adat létrehozásakor egyszer megjelenített hozzáférésikulcs-titok
Az API-kibocsátó azonosítója (issuer ID), amelyet a Living Security a Public API hitelesítő adataival együtt biztosít
Az integrálandó szervezethez tartozó regionális alap-URL
Szerveroldali futtatókörnyezet és titokkezelő

A hozzáférésikulcs-titkokat tilos böngészőkódban, mobilalkalmazásokban, verziókezelőben, kliensoldali környezeti változókban, jegyekben vagy megosztott naplókban elhelyezni.

Az Access Keys párbeszédablak megjeleníti az egyszer látható titkot, de nem mutatja az API-kibocsátó azonosítóját. Ha a Living Security nem adta meg az issuer ID-t a Public API hitelesítő adataival együtt, kérje el a Living Security ügyfélszolgálatától. Az issuer ID nem azonos a hozzáférési kulcs azonosítójával vagy a szervezet azonosítójával.

Regionális hosztok

A régi szerződés a következő regionális /api/v1 éles hosztokat használja:

Régió	Alap-URL
US	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Használja a Living Security szervezethez hozzárendelt régiót. Ne váltson régiót egy engedélyezési vagy rendelkezésre állási hiba megkerülésére.

Régi erőforrások

Erőforrás	Támogatott műveletek
Emberek	A szervezet személyeinek keresése és egy személy tagságának lekérése
API-hozzáférési kulcsok	API-hozzáférési kulcsok létrehozása, listázása, cseréje és visszavonása

A teljes művelet-, paraméter-, kérés-, válasz- és sémalistát a Developers → Public API Reference menüpont alatt találja. Ha egy művelet nem szerepel ott, akkor jelenleg nem része a Public API-nak.

Hitelesítés

A Public API-hozzáférés két lépésből áll:

Cserélje a titkos hozzáférési kulcsot és az API-kibocsátó azonosítóját rövid élettartamú bearer tokenre és szervezetazonosítóra.
Minden API-kéréssel küldje el a bearer tokent és a szervezetazonosítót.

A szükséges kérésfejlécek:

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

A szervezetfejlécnek a hozzáférésikulcs-csere által visszaadott szervezetnek kell lennie. Egy kulcs nem jogosít fel hozzáférésre tetszőleges szervezetazonosítóhoz.

TypeScript SDK

Telepítse az aktuális főverziót:

npm install @livingsecurity/sdk@^1

Ezután cserélje le a kulcsot, és konfigurálja az SDK-t:

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,
});

EU-szervezet esetén használja az EU alap-URL-t. Az SDK-s csere szerveroldali Node.js futtatókörnyezetekhez készült.

Közvetlen REST-kérés

Ha a cserét az SDK-n kívül végzi el, minden kéréssel küldje el a kapott bearer tokent és szervezetazonosítót:

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"

A bearer tokenek rövid élettartamúak. Új token beszerzéséhez cserélje le újra a hozzáférési kulcsot, ne tárolja a bearer tokent tartós hitelesítő adatként.

A hozzáférési kulcsok életciklusa

A kulcsokat a tulajdonos integrációról vagy automatizálásról nevezze el.
Válassza a hozzáférésikulcs-űrlapon kínált legkisebb jogosultságú hatóköröket.
Az egyszer megjelenített titkot azonnal tárolja el; létrehozás vagy csere után nem kérhető le újra.
A kulcsot a Beállítások → Access Keys menüpontban cserélje, és a régi hitelesítő adat visszavonása előtt telepítse a cserekulcsot.
Vonja vissza azokat a kulcsokat, amelyeket már nem használ, vagy amelyek titka nyilvánosságra kerülhetett.
Nem emberi integrációkhoz használjon szolgáltatásfiók-kulcsokat, ha ez a kulcstípus elérhető a szervezete számára.

Lapozás

Az emberek keresése támogatja a limit, cursor, offset és includeTotal paramétereket. Szekvenciális bejáráshoz az előző válaszban visszaadott kurzort részesítse előnyben.

A limit alapértelmezett értéke 50, és 1–100 közötti értéket fogad el.
A cursor egy korábbi válasz folytatását kéri.
A offset adott számú rekordot kihagy, alapértelmezett értéke 0.
A includeTotal=true pontos, szűrt darabszámot kér; ha nincs szüksége a darabszámra, hagyja el.

Olvassa el a végpont által visszaadott pagination objektumot. Ne a kapott sorok számából számítsa ki a következő oldalt, és ne egyesítse egymástól függetlenül lapozott kérések eredményeit, hogy aztán saját maga rendezze a részeredményeket.

Hibák

A dokumentált JSON-hibák általános szerkezete:

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

A message lehet karakterlánc vagy érvényesítési üzenetek tömbje.

Állapot	Jelentés	Teendő
`400`	Érvénytelen paraméterek vagy kérés törzse	Javítsa a megnevezett érvényesítési hibákat
`401`	A bearer token hiányzik, érvénytelen vagy lejárt	Cserélje le újra a hozzáférési kulcsot, és egyszer próbálja újra
`403`	A hitelesítő adat nem rendelkezik jogosultsággal vagy szervezeti hozzáféréssel	Ellenőrizze a kulcs hatóköreit és a szervezeti környezetet
`404`	Az erőforrás nem létezik a jogosult szervezetben	Ellenőrizze az erőforrás azonosítóját és a szervezetet
`408`	A kérés időtúllépés miatt megszakadt	Próbálja újra korlátozott exponenciális visszalépéssel
`429`	Elérte a sebességkorlátot	Várjon legalább `Retry-After` értékének megfelelő ideig, ha szerepel
`5xx`	Átmeneti szolgáltatáshiba	A biztonságos olvasásokat próbálja újra korlátozott exponenciális visszalépéssel

A gondozott szerződés jelenleg nem tesz közzé egyetlen, mindenre érvényes numerikus sebességkorlátot, és nem garantál kérésazonosító-válaszfejlécet minden művelethez. Az ügyfélszolgálati megkeresés során adja meg az UTC-időpontot, a metódust, az útvonalat, az állapotkódot és a megtisztított választörzset. Ne próbálja meg automatikusan újra a létrehozási, cserélési, visszavonási vagy törlési műveleteket, kivéve, ha a művelet kifejezetten dokumentálja az idempotenciát. Bizonytalan hálózati hiba után ellenőrizze az erőforrás aktuális állapotát.

Kompatibilitás és elavulás

A V1 alapértelmezés szerint additív módon fejlődik. Az ügyfeleknek figyelmen kívül kell hagyniuk az ismeretlen válaszmezőket. Egy törést okozó változtatáshoz dokumentált migrációs útvonal szükséges; az elavult műveletek az áttérési időszak alatt az indoklásukkal, elérhetőség esetén a helyettesítő művelettel és a megszüntetés dátumával együtt szerepelnek a referenciában. Rögzítse az SDK-t egy kompatibilis főverzióra, és frissítés előtt tekintse át a kiadási megjegyzéseit. A generált Public API Reference-t tekintse a séma hiteles forrásának, ne az elsődleges gyártói alkalmazásklienseket.

Public API, MCP és a webalkalmazás

Felület	Felhasználás	Kompatibilitási modell
Public API	Ügyfélrendszerek, partnerek és külső automatizálás	Stabil, verziózott erőforrások
MCP	Jogosultsághoz kötött AI-eszközinterakciók	Eszközszerződések és tömör strukturált kimenetek
Webalkalmazás	Emberi munkafolyamatok a Living Security termékben	Az alkalmazás tulajdonában lévő szerződések, amelyek a felülettel együtt változhatnak

Az AI-eszközök Living Security-hez történő csatlakoztatásáról lásd az MCP-integrációt.

Segítségkérés

Forduljon a Living Security ügyfélszolgálatához a következő adatokkal:

Szervezet és régió
Az SDK neve és verziója, ha használja
UTC-időbélyeg, metódus és útvonal
HTTP-állapotkód és megtisztított hibatörzs

Soha ne küldjön hozzáférésikulcs-titkokat, bearer tokeneket vagy privát ügyféladatokat.

Kapcsolódó

API Access Keys

API-hitelesítő adatok létrehozása, cseréje és visszavonása.

MCP Integration

Támogatott AI-eszközök csatlakoztatása a Model Context Protocolon keresztül.

Nyilvános API

Nyilvános API-referencia

Előkészületek

Regionális hosztok

Régi erőforrások

Hitelesítés

TypeScript SDK

Közvetlen REST-kérés

A hozzáférési kulcsok életciklusa

Lapozás

Hibák

Kompatibilitás és elavulás

Public API, MCP és a webalkalmazás

Segítségkérés

Kapcsolódó

API Access Keys

MCP Integration

Nyilvános API

Nyilvános API-referencia

​Előkészületek

​Regionális hosztok

​Régi erőforrások

​Hitelesítés

​TypeScript SDK

​Közvetlen REST-kérés

​A hozzáférési kulcsok életciklusa

​Lapozás

​Hibák

​Kompatibilitás és elavulás

​Public API, MCP és a webalkalmazás

​Segítségkérés

​Kapcsolódó

API Access Keys

MCP Integration

Előkészületek

Regionális hosztok

Régi erőforrások

Hitelesítés

TypeScript SDK

Közvetlen REST-kérés

A hozzáférési kulcsok életciklusa

Lapozás

Hibák

Kompatibilitás és elavulás

Public API, MCP és a webalkalmazás

Segítségkérés

Kapcsolódó