Ghid de pornire rapidă pentru API

Creați un cont de serviciu și o cheie API în Developer Hub, apoi efectuați prima solicitare. Acest ghid de pornire rapidă utilizează autentificarea cu cheie API; nu aveți nevoie de un client OAuth. Consultați Autentificare dacă integrarea dvs. necesită tokeni de acces OAuth cu durată scurtă de viață.

Cerințe preliminare

Acces de administrator la Tabloul de bord Living Security.
Developer Hub vizibil la Setări → Integrări & Developers → Developer Hub.

Crearea datelor de autentificare

Creați un cont de serviciu

În Developer Hub, deschideți fila Service accounts și creați un cont. Atribuiți-i un nume descriptiv (de exemplu reporting-pipeline) și acordați permisiunile pe care le pot utiliza cheile sale — pentru acest ghid, organization:read este suficientă.Permisiunile contului reprezintă limita maximă pentru fiecare cheie creată în cadrul lui: o cheie nu poate face niciodată mai mult decât permite contul de serviciu căruia îi aparține.

Creați o cheie API

Deschideți pagina de detalii a contului de serviciu și creați o cheie. Alegeți permisiunile de care are nevoie această cheie anume (un subset al celor ale contului) și o expirare — 30, 90 sau 365 de zile ori o perioadă personalizată. Expirarea este obligatorie.Secretul cheii începe cu lsk_live_ și este afișat o singură dată. Copiați-l imediat într-un manager de secrete; nu mai poate fi recuperat ulterior.

Nu includeți niciodată secretele cheilor API în controlul versiunilor și nu le încorporați în codul din partea clientului. Oricine deține secretul poate acționa cu permisiunile cheii.

Alegeți regiunea

Apelați gazda regională /v1 care corespunde rezidenței datelor organizației. Cheile se autentifică numai pe acea gazdă.

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

Consultați Regiuni dacă nu sunteți sigur ce gazdă să utilizați. O cheie validă trimisă către cealaltă regiune eșuează cu unauthorized. Utilizați lista verticală de regiuni din exemplul de mai jos pentru a comuta gazda.

Efectuați prima solicitare

Încărcați LIVING_SECURITY_API_KEY din managerul de secrete în mediul procesului care efectuează solicitarea. Exemplele de mai jos îl citesc fără a încorpora un secret în codul sursă. Pentru Python, instalați mai întâi requests.Apelați API-ul cu secretul în câmpul de parolă sau în cel de nume de utilizator ale autentificării HTTP Basic — oricare funcționează, astfel încât clienții care necesită completarea ambelor câmpuri (precum conectorul Web din Power BI) pot introduce un substituent, cum ar fi apikey, în celălalt câmp.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

Un răspuns reușit returnează organizația dvs.:

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

Dacă primiți acest răspuns, datele dvs. de autentificare funcționează. Solicitarea apare, de asemenea, în fila Request logs din Developer Hub în câteva momente.

Autentificarea Bearer cu același secret (Authorization: Bearer lsk_live_...) funcționează, de asemenea. Autentificarea Basic există pentru ca instrumentele care acceptă doar nume de utilizator/parolă — precum conectorul Web din Power BI — să se poată conecta.

Cum funcționează autentificarea

Datele de autentificare determină organizația. Solicitările /v1 nu conțin niciun selector de tenant: niciun segment de cale pentru organizație și niciun antet pentru organizație. Trimiterea unui antet x-organization-id este respinsă cu invalid_request. Gazda trebuie în continuare să corespundă regiunii acelei organizații. Consultați Regiuni.
Permisiunile sunt verificate pentru fiecare operațiune. Fiecare operațiune /v1 necesită o permisiune numită (de exemplu, GET /v1/organization necesită organization:read). O cheie care nu are permisiunea primește 403 cu codul insufficient_permission.
Cheile expiră și pot fi rotite fără întreruperi. Consultați Chei API pentru rotirea cu o fereastră de suprapunere.

Citirea răspunsurilor de eroare

Fiecare eroare /v1 este application/problem+json (RFC 9457) cu un cod stabil care poate fi citit automat. De exemplu, o solicitare cu date de autentificare lipsă sau necunoscute returnează:

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

Ramificați logica pe baza code, niciodată a detail. Urmați doc_url pentru pașii de rezolvare și includeți request_id când contactați asistența — acesta corespunde antetului de răspuns Request-Id și jurnalelor de solicitări din Developer Hub. Setul complet de coduri se află în referința de erori.

Versiunile contractului

Fiecare răspuns returnează versiunea contractului care l-a deservit în antetul Living-Security-Version, alături de un antet Request-Id pentru corelare. Puteți fixa o solicitare la o versiune publicată a contractului după dată:

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

Versiunea se stabilește în această ordine: antetul solicitării, dacă există, altfel versiunea implicită fixată a contului de serviciu, altfel cea mai recentă versiune publicată. Solicitarea unei versiuni care nu este publicată (sau care a depășit data de retragere) returnează 400 cu codul unsupported_version. Versiunile publicate și modificările lor sunt listate în jurnalul de modificări al API-ului.

Depanarea primei solicitări

Rezultat	Acțiune următoare
`401 unauthorized`	Verificați secretul, expirarea acestuia și regiunea organizației. Nu încercați alte gazde cu date de autentificare active.
`403 insufficient_permission`	Acordați `organization:read` atât contului de serviciu, cât și cheii sale.
`400 unsupported_version`	Alegeți o versiune publicată din jurnalul de modificări.
`429 rate_limited`	Așteptați `Retry-After`; urmați exemplul de reîncercare limitată.
Expirarea timpului de rețea	Verificați conectivitatea și reîncercați această citire în limita bugetului de reîncercări al aplicației dvs.

Pentru alte erori, urmați doc_url din răspuns. Păstrați Request-Id pentru asistență; nu includeți niciodată antetul Authorization sau cheia API într-un tichet.

Pașii următori

Regiuni

Alegeți gazda /v1 din SUA sau UE pentru organizație.

Paginare

Parcurgeți listele cu page_token și învelișul listei.

Limite de rată

Înțelegeți bugetele de solicitări și gestionați răspunsurile 429.

Referință de erori

Fiecare cod de eroare, starea sa HTTP și modul de rezolvare.

Developer Hub

Gestionați conturile de serviciu, cheile API și jurnalele de solicitări.

Hub pentru dezvoltatori

API public v1

Referință API v1

Cerințe preliminare

Crearea datelor de autentificare

Cum funcționează autentificarea

Citirea răspunsurilor de eroare

Versiunile contractului

Depanarea primei solicitări

Pașii următori

Regiuni

Paginare

Limite de rată

Referință de erori

Developer Hub

Hub pentru dezvoltatori

API public v1

Referință API v1

​Cerințe preliminare

​Crearea datelor de autentificare

​Cum funcționează autentificarea

​Citirea răspunsurilor de eroare

​Versiunile contractului

​Depanarea primei solicitări

​Pașii următori

Regiuni

Paginare

Limite de rată

Referință de erori

Developer Hub

Cerințe preliminare

Crearea datelor de autentificare

Cum funcționează autentificarea

Citirea răspunsurilor de eroare

Versiunile contractului

Depanarea primei solicitări

Pașii următori