API public Legacy - Living Security Platform

Acest ghid se referă la integrările /api/v1 existente, care schimbă o cheie de acces API pentru un token bearer. Datele de autentificare și formatul cererilor diferă de cele ale API-ului public /v1. Pentru o integrare nouă, începeți cu Ghidul de pornire rapidă API și cu Autentificarea. Noul API /v1 utilizează chei API de cont de serviciu sau tokenuri de acces OAuth.

Înainte de a începe

Aveți nevoie de:

Acces Living Security care permite gestionarea cheilor de acces API
O cheie de acces API creată la Setări → Access Keys
Secretul cheii de acces, afișat o singură dată la crearea datelor de autentificare
ID-ul emitentului API, furnizat de Living Security împreună cu datele dvs. de autentificare pentru API-ul public
URL-ul de bază regional pentru organizația pe care o integrați
Un mediu de execuție pe server și un manager de secrete

Secretele cheilor de acces nu trebuie plasate în codul din browser, în aplicații mobile, în controlul versiunilor, în variabile de mediu de pe partea client, în tichete sau în jurnale partajate.

Caseta de dialog Access Keys afișează secretul unic, dar nu afișează ID-ul emitentului API. Dacă Living Security nu a furnizat ID-ul emitentului împreună cu datele dvs. de autentificare pentru API-ul public, solicitați-l de la asistența Living Security. ID-ul emitentului nu este ID-ul cheii de acces și nici ID-ul organizației.

Gazde regionale

Contractul legacy utilizează aceste gazde regionale de producție /api/v1:

Regiune	URL de bază
SUA	`https://api.us-east-1.livingsecurity.ai/api/v1`
UE	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Utilizați regiunea atribuită organizației Living Security. Nu schimbați regiunea pentru a ocoli o eroare de autorizare sau de disponibilitate.

Resurse legacy

Resursă	Operațiuni acceptate
Oameni	Căutarea persoanelor din organizație și preluarea apartenenței unei persoane
Chei de acces API	Crearea, listarea, rotirea și revocarea cheilor de acces API

Utilizați Developers → Public API Reference pentru lista completă de operațiuni, parametri, cereri, răspunsuri și scheme. Dacă o operațiune nu se află acolo, nu face parte în prezent din API-ul public.

Autentificare

Accesul la API-ul public are două etape:

Schimbați cheia de acces secretă și ID-ul emitentului API pentru un token bearer de scurtă durată și un ID de organizație.
Trimiteți tokenul bearer și ID-ul organizației cu fiecare cerere API.

Antetele de cerere necesare sunt:

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

Antetul organizației trebuie să conțină organizația returnată de schimbul cheii de acces. O cheie nu autorizează accesul la un ID de organizație arbitrar.

SDK TypeScript

Instalați versiunea majoră curentă:

npm install @livingsecurity/sdk@^1

Apoi schimbați cheia și configurați SDK-ul:

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

Utilizați URL-ul de bază pentru UE în cazul unei organizații din UE. Schimbul prin SDK este destinat mediilor de execuție Node.js de pe server.

Cerere REST directă

Dacă efectuați schimbul în afara SDK-ului, trimiteți tokenul bearer și ID-ul organizației cu fiecare cerere:

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"

Tokenurile bearer sunt de scurtă durată. Schimbați din nou cheia de acces atunci când obțineți un token nou, în loc să păstrați un token bearer ca date de autentificare permanente.

Ciclul de viață al cheii de acces

Denumiți cheile după integrarea sau automatizarea căreia îi aparțin.
Alegeți domeniile de aplicare (scopes) cu cele mai puține privilegii oferite de formularul cheii de acces.
Stocați imediat secretul afișat o singură dată; acesta nu mai poate fi recuperat după creare sau rotire.
Rotiți o cheie din Setări → Access Keys și implementați cheia de înlocuire înainte de a revoca datele de autentificare vechi.
Revocați cheile care nu mai sunt utilizate sau al căror secret ar putea fi expus.
Utilizați chei de cont de serviciu pentru integrările non-umane, atunci când acest tip de cheie este disponibil organizației dvs.

Paginare

Căutarea în Oameni acceptă parametrii limit, cursor, offset și includeTotal. Pentru parcurgerea secvențială, preferați cursorul returnat de răspunsul anterior.

limit are valoarea implicită 50 și acceptă valori între 1 și 100.
cursor continuă de la un răspuns anterior.
offset omite un număr de înregistrări și are valoarea implicită 0.
includeTotal=true solicită un număr exact filtrat; omiteți-l atunci când numărul nu este necesar.

Citiți obiectul pagination returnat de endpoint. Nu calculați pagina următoare pe baza numărului de rânduri primite și nu combinați cereri paginate independent pentru a sorta apoi singuri rezultatele parțiale.

Erori

Erorile JSON documentate au această formă generală:

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

message poate fi un șir de caractere sau o matrice de mesaje de validare.

Stare	Semnificație	Răspuns
`400`	Parametri sau corp al cererii nevalid(e)	Corectați erorile de validare indicate
`401`	Tokenul bearer lipsește, este nevalid sau a expirat	Schimbați din nou cheia de acces și reîncercați o dată
`403`	Datele de autentificare nu au permisiunea sau accesul la organizație	Verificați domeniile cheii și contextul organizației
`404`	Resursa nu există în organizația autorizată	Verificați ID-ul resursei și organizația
`408`	Cererea a expirat	Reîncercați cu backoff exponențial limitat
`429`	Limita de cereri a fost atinsă	Așteptați cel puțin cât indică `Retry-After`, când este prezent
`5xx`	Eroare temporară a serviciului	Reîncercați citirile sigure cu backoff exponențial limitat

Contractul curatoriat nu publică în prezent o limită numerică universală de cereri și nu garantează un antet de răspuns cu ID-ul cererii pentru fiecare operațiune. Când solicitați asistență, rețineți ora UTC, metoda, calea, starea și corpul răspunsului, după eliminarea datelor sensibile. Nu reîncercați automat operațiunile de creare, rotire, revocare sau ștergere, decât dacă operațiunea documentează explicit idempotența. După o defecțiune de rețea ambiguă, verificați starea curentă a resursei.

Compatibilitate și depreciere

V1 evoluează în mod implicit prin adăugiri. Clienții trebuie să ignore câmpurile necunoscute din răspuns. O modificare care întrerupe compatibilitatea necesită o cale de migrare documentată; operațiunile depreciate rămân în referință, cu motivul, înlocuitorul (când există) și data încheierii suportului în timpul perioadei de migrare. Fixați SDK-ul la o versiune majoră compatibilă și consultați notele de lansare înainte de actualizare. Considerați Public API Reference generată, și nu clienții aplicațiilor proprii, drept sursa de adevăr pentru schemă.

API public, MCP și aplicația web

Suprafață	Utilizare	Model de compatibilitate
API public	Sisteme ale clienților, parteneri și automatizare externă	Resurse stabile, versionate
MCP	Interacțiuni cu instrumente AI, bazate pe permisiuni	Contracte ale instrumentelor și ieșiri structurate compacte
Aplicația web	Fluxuri de lucru umane în produsul Living Security	Contracte deținute de aplicație, care pot evolua odată cu interfața

Consultați Integrarea MCP pentru a conecta un instrument AI la Living Security.

Obținerea asistenței

Contactați asistența Living Security și includeți:

Organizația și regiunea
Numele și versiunea SDK-ului, dacă este utilizat
Marcajul de timp UTC, metoda și calea
Starea HTTP și corpul erorii, după eliminarea datelor sensibile

Nu includeți niciodată secrete ale cheilor de acces, tokenuri bearer sau date private ale clienților.

Chei de acces API

Creați, rotiți și revocați datele de autentificare API.

Integrarea MCP

Conectați instrumentele AI acceptate prin Model Context Protocol.

API public

Referință API public

​Înainte de a începe

​Gazde regionale

​Resurse legacy

​Autentificare

​SDK TypeScript

​Cerere REST directă

​Ciclul de viață al cheii de acces

​Paginare

​Erori

​Compatibilitate și depreciere

​API public, MCP și aplicația web

​Obținerea asistenței

​Related

Chei de acces API

Integrarea MCP

Înainte de a începe

Gazde regionale

Resurse legacy

Autentificare

SDK TypeScript

Cerere REST directă

Ciclul de viață al cheii de acces

Paginare

Erori

Compatibilitate și depreciere

API public, MCP și aplicația web

Obținerea asistenței

Related