Starsza wersja publicznego API

Ten przewodnik dotyczy istniejących integracji /api/v1, które wymieniają klucz dostępu API na token okaziciela. Ich dane uwierzytelniające oraz format żądań różnią się od publicznego API /v1. W przypadku nowej integracji zacznij od krótkiego wprowadzenia do API oraz sekcji Uwierzytelnianie. Nowe API /v1 korzysta z kluczy API kont usługowych lub tokenów dostępu OAuth.

Zanim zaczniesz

Potrzebne są:

Dostęp do Living Security z uprawnieniami do zarządzania kluczami dostępu API
Klucz dostępu API utworzony w sekcji Ustawienia → Access Keys
Jednorazowy sekret klucza dostępu wyświetlany podczas tworzenia danych uwierzytelniających
Identyfikator wystawcy API (API issuer ID) przekazany przez Living Security wraz z danymi uwierzytelniającymi publicznego API
Regionalny bazowy adres URL organizacji, którą integrujesz
Środowisko uruchomieniowe po stronie serwera oraz menedżer sekretów

Sekretów kluczy dostępu nie wolno umieszczać w kodzie przeglądarki, aplikacjach mobilnych, repozytoriach kodu źródłowego, zmiennych środowiskowych po stronie klienta, zgłoszeniach ani we wspólnych dziennikach.

Okno Access Keys wyświetla jednorazowy sekret, ale nie pokazuje identyfikatora wystawcy API (API issuer ID). Jeśli Living Security nie przekazało identyfikatora wystawcy wraz z danymi uwierzytelniającymi publicznego API, poproś o niego pomoc techniczną Living Security. Identyfikator wystawcy nie jest identyfikatorem klucza dostępu ani identyfikatorem organizacji.

Hosty regionalne

Starsza specyfikacja korzysta z następujących regionalnych hostów produkcyjnych /api/v1:

Region	Bazowy adres URL
US	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Użyj regionu przypisanego do organizacji w Living Security. Nie zmieniaj regionu, aby obejść błąd autoryzacji lub dostępności.

Starsze zasoby

Zasób	Obsługiwane operacje
Ludzie	Wyszukiwanie osób w organizacji i pobieranie członkostwa danej osoby
Klucze dostępu API	Tworzenie, wyświetlanie, rotacja i unieważnianie kluczy dostępu API

Pełną listę operacji, parametrów, żądań, odpowiedzi i schematów znajdziesz w sekcji Developers → Public API Reference. Jeśli operacji tam nie ma, nie jest ona obecnie częścią publicznego API.

Uwierzytelnianie

Dostęp do publicznego API przebiega w dwóch etapach:

Wymień sekret klucza dostępu i identyfikator wystawcy API (API issuer ID) na krótkotrwały token okaziciela i identyfikator organizacji.
Przesyłaj token okaziciela i identyfikator organizacji z każdym żądaniem API.

Wymagane nagłówki żądania to:

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

Nagłówek organizacji musi zawierać organizację zwróconą podczas wymiany klucza dostępu. Klucz nie uprawnia do dostępu do dowolnego identyfikatora organizacji.

SDK dla TypeScript

Zainstaluj bieżącą wersję główną:

npm install @livingsecurity/sdk@^1

Następnie wymień klucz i skonfiguruj SDK:

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

W przypadku organizacji z regionu EU użyj bazowego adresu URL dla EU. Wymiana w SDK jest przeznaczona dla środowisk Node.js działających po stronie serwera.

Bezpośrednie żądanie REST

Jeśli wymiany dokonujesz poza SDK, przesyłaj uzyskany token okaziciela i identyfikator organizacji w każdym żądaniu:

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"

Tokeny okaziciela są krótkotrwałe. Aby uzyskać nowy token, ponownie wymień klucz dostępu, zamiast przechowywać token okaziciela jako stałe dane uwierzytelniające.

Cykl życia klucza dostępu

Nazywaj klucze według integracji lub automatyzacji, do której należą.
Wybieraj najmniej uprzywilejowane zakresy dostępne w formularzu klucza dostępu.
Zapisz jednorazowy sekret natychmiast; po utworzeniu lub rotacji nie można go ponownie pobrać.
Wykonaj rotację klucza w sekcji Ustawienia → Access Keys i wdróż klucz zastępczy przed unieważnieniem starych danych uwierzytelniających.
Unieważniaj klucze, które nie są już używane lub których sekret mógł zostać ujawniony.
W przypadku integracji nieobsługiwanych przez człowieka używaj kluczy kont usługowych, jeśli ten typ klucza jest dostępny w Twojej organizacji.

Stronicowanie

Wyszukiwanie osób obsługuje parametry limit, cursor, offset i includeTotal. Do sekwencyjnego przechodzenia po wynikach używaj kursora zwróconego w poprzedniej odpowiedzi.

limit domyślnie wynosi 50 i przyjmuje wartości 1–100.
cursor kontynuuje od poprzedniej odpowiedzi.
offset pomija określoną liczbę rekordów i domyślnie wynosi 0.
includeTotal=true żąda dokładnej liczby przefiltrowanych rekordów; pomiń go, jeśli liczba nie jest potrzebna.

Odczytaj obiekt pagination zwrócony przez punkt końcowy. Nie oblicza się następnej strony na podstawie liczby otrzymanych wierszy ani nie łączy niezależnie stronicowanych żądań z samodzielnym sortowaniem częściowych wyników.

Błędy

Udokumentowane błędy JSON mają następującą ogólną postać:

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

message może być ciągiem znaków lub tablicą komunikatów walidacji.

Status	Znaczenie	Postępowanie
`400`	Nieprawidłowe parametry lub treść żądania	Popraw wskazane błędy walidacji
`401`	Token okaziciela jest nieobecny, nieprawidłowy lub wygasł	Ponownie wymień klucz dostępu i ponów próbę jednokrotnie
`403`	Dane uwierzytelniające nie mają uprawnień lub dostępu do organizacji	Sprawdź zakresy klucza i kontekst organizacji
`404`	Zasób nie istnieje w autoryzowanej organizacji	Zweryfikuj identyfikator zasobu i organizację
`408`	Upłynął limit czasu żądania	Ponów próbę, stosując ograniczony wykładniczy odstęp (backoff)
`429`	Osiągnięto limit szybkości żądań	Odczekaj co najmniej tyle, ile wskazuje `Retry-After`, jeśli występuje
`5xx`	Przejściowa awaria usługi	Ponawiaj bezpieczne odczyty, stosując ograniczony wykładniczy odstęp (backoff)

Ta wyselekcjonowana specyfikacja nie publikuje obecnie jednego uniwersalnego limitu liczbowego szybkości żądań ani nie gwarantuje nagłówka odpowiedzi z identyfikatorem żądania dla każdej operacji. Zgłaszając się do pomocy technicznej, podaj czas UTC, metodę, ścieżkę, status i oczyszczoną treść odpowiedzi. Nie ponawiaj automatycznie operacji tworzenia, rotacji, unieważniania ani usuwania, chyba że dana operacja wyraźnie dokumentuje idempotentność. Po niejednoznacznej awarii sieci sprawdź aktualny stan zasobu.

Zgodność i wycofywanie

Wersja V1 domyślnie rozwija się w sposób addytywny. Klienci muszą ignorować nieznane pola odpowiedzi. Zmiana łamiąca zgodność wymaga udokumentowanej ścieżki migracji; wycofywane operacje pozostają w dokumentacji referencyjnej wraz z powodem, zamiennikiem (jeśli jest dostępny) oraz datą wycofania w okresie migracji. Przypnij SDK do zgodnej wersji głównej i przed aktualizacją zapoznaj się z informacjami o wydaniu. Jako źródło prawdy dla schematów traktuj wygenerowaną dokumentację Public API Reference, a nie własne aplikacje klienckie.

Publiczne API, MCP i aplikacja webowa

Powierzchnia	Zastosowanie	Model zgodności
Publiczne API	Systemy klientów, partnerzy i automatyzacja zewnętrzna	Stabilne, wersjonowane zasoby
MCP	Interakcje narzędzi AI z kontrolą uprawnień	Kontrakty narzędzi i zwięzłe uporządkowane wyniki
Aplikacja webowa	Procesy realizowane przez użytkowników w produkcie Living Security	Kontrakty należące do aplikacji, które mogą zmieniać się wraz z interfejsem

Aby połączyć narzędzie AI z Living Security, zobacz Integracja MCP.

Uzyskiwanie pomocy

Skontaktuj się z pomocą techniczną Living Security, podając:

Organizację i region
Nazwę i wersję SDK, jeśli jest używane
Znacznik czasu UTC, metodę i ścieżkę
Status HTTP i oczyszczoną treść błędu

Nigdy nie dołączaj sekretów kluczy dostępu, tokenów okaziciela ani prywatnych danych klientów.

Publiczne API

Dokumentacja referencyjna publicznego API

Zanim zaczniesz

Hosty regionalne

Starsze zasoby

Uwierzytelnianie

SDK dla TypeScript

Bezpośrednie żądanie REST

Cykl życia klucza dostępu

Stronicowanie

Błędy

Zgodność i wycofywanie

Publiczne API, MCP i aplikacja webowa

Uzyskiwanie pomocy

Powiązane

Klucze dostępu API

Integracja MCP

Publiczne API

Dokumentacja referencyjna publicznego API

​Zanim zaczniesz

​Hosty regionalne

​Starsze zasoby

​Uwierzytelnianie

​SDK dla TypeScript

​Bezpośrednie żądanie REST

​Cykl życia klucza dostępu

​Stronicowanie

​Błędy

​Zgodność i wycofywanie

​Publiczne API, MCP i aplikacja webowa

​Uzyskiwanie pomocy

​Powiązane

Klucze dostępu API

Integracja MCP

Zanim zaczniesz

Hosty regionalne

Starsze zasoby

Uwierzytelnianie

SDK dla TypeScript

Bezpośrednie żądanie REST

Cykl życia klucza dostępu

Stronicowanie

Błędy

Zgodność i wycofywanie

Publiczne API, MCP i aplikacja webowa

Uzyskiwanie pomocy

Powiązane