> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API public Legacy

> Întrețineți integrările existente /api/v1 care schimbă o cheie de acces API pentru un token bearer.

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](/ro/developers/v1/quickstart) și cu [Autentificarea](/ro/developers/v1/authentication). 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.

<Note>
  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](mailto:support@livingsecurity.com). ID-ul
  emitentului nu este ID-ul cheii de acces și nici ID-ul organizației.
</Note>

## 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:

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

Antetele de cerere necesare sunt:

```http theme={null}
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ă:

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

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

```typescript theme={null}
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:

```bash theme={null}
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ă:

```json theme={null}
{
  "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](/ro/integrations/mcp) pentru a conecta un instrument AI la Living Security.

## Obținerea asistenței

Contactați [asistența Living Security](mailto:support@livingsecurity.com) ș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.

## Related

<CardGroup cols={2}>
  <Card title="Chei de acces API" icon="key" href="/ro/integrations/api-keys">
    Creați, rotiți și revocați datele de autentificare API.
  </Card>

  <Card title="Integrarea MCP" icon="robot" href="/ro/integrations/mcp">
    Conectați instrumentele AI acceptate prin Model Context Protocol.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.