Legacy Public API

Šajā rokasgrāmatā aprakstītas esošās /api/v1 integrācijas, kas apmaina API piekļuves atslēgu pret nesēja pilnvaru (bearer token). To akreditācijas dati un pieprasījumu formāts atšķiras no /v1 Public API. Jaunai integrācijai sāciet ar API quickstart un Authentication. Jaunais /v1 API izmanto servisa kontu API atslēgas vai OAuth piekļuves pilnvaras.

Pirms sākat

Jums ir nepieciešams:

Living Security piekļuve, kas ļauj pārvaldīt API piekļuves atslēgas
API piekļuves atslēga, kas izveidota sadaļā Settings → Access Keys
Vienreizējais piekļuves atslēgas noslēpums, kas tiek parādīts, izveidojot akreditācijas datus
API izsniedzēja ID (issuer ID), ko kopā ar Public API akreditācijas datiem nodrošina Living Security
Reģionālais bāzes URL organizācijai, ar kuru veicat integrāciju
Servera puses izpildes vide un noslēpumu pārvaldnieks

Piekļuves atslēgu noslēpumus nedrīkst ievietot pārlūkprogrammas kodā, mobilajās lietotnēs, versiju kontrolē, klienta puses vides mainīgajos, pieteikumos vai koplietotos žurnālos.

Dialoglodziņā Access Keys tiek parādīts vienreizējais noslēpums, taču netiek rādīts API izsniedzēja ID. Ja Living Security nav nodrošinājis izsniedzēja ID kopā ar jūsu Public API akreditācijas datiem, pieprasiet to Living Security atbalstam. Izsniedzēja ID nav piekļuves atslēgas ID vai organizācijas ID.

Reģionālie resursdatori

Mantotais līgums izmanto šādus reģionālos /api/v1 produkcijas resursdatorus:

Reģions	Bāzes URL
US	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Izmantojiet reģionu, kas piešķirts Living Security organizācijai. Nemainiet reģionus, lai apietu autorizācijas vai pieejamības kļūdu.

Mantotie resursi

Resurss	Atbalstītās darbības
People	Meklēt organizācijas personas un iegūt personas dalības informāciju
API access keys	Izveidot, uzskaitīt, rotēt un atsaukt API piekļuves atslēgas

Pilnīgu darbību, parametru, pieprasījumu, atbilžu un shēmu sarakstu skatiet sadaļā Developers → Public API Reference. Ja darbības tur nav, tā pašlaik nav Public API daļa.

Autentifikācija

Public API piekļuve ir divos posmos:

Apmainiet slepeno piekļuves atslēgu un API izsniedzēja ID pret īslaicīgu nesēja pilnvaru un organizācijas ID.
Sūtiet nesēja pilnvaru un organizācijas ID ar katru API pieprasījumu.

Nepieciešamie pieprasījuma galvenes lauki ir:

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

Organizācijas galvenē jānorāda organizācija, ko atgriezusi piekļuves atslēgas apmaiņa. Atslēga nedod piekļuvi patvaļīgam organizācijas ID.

TypeScript SDK

Instalējiet pašreizējo galveno versiju:

npm install @livingsecurity/sdk@^1

Pēc tam apmainiet atslēgu un konfigurējiet 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,
});

EU organizācijai izmantojiet EU bāzes URL. SDK apmaiņa paredzēta servera puses Node.js izpildes vidēm.

Tiešs REST pieprasījums

Ja apmaiņu veicat ārpus SDK, sūtiet tās nesēja pilnvaru un organizācijas ID ar katru pieprasījumu:

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"

Nesēja pilnvaras ir īslaicīgas. Lai iegūtu jaunu pilnvaru, vēlreiz apmainiet piekļuves atslēgu, nevis saglabājiet nesēja pilnvaru kā pastāvīgus akreditācijas datus.

Piekļuves atslēgas dzīves cikls

Nosauciet atslēgas pēc integrācijas vai automatizācijas, kurai tās pieder.
Izvēlieties piekļuves atslēgas veidlapā piedāvātos apjomus (scopes) ar vismazākajām privilēģijām.
Nekavējoties saglabājiet vienreizējo noslēpumu; pēc izveides vai rotācijas to nevar atgūt.
Rotējiet atslēgu sadaļā Settings → Access Keys un ieviesiet aizstājēju pirms vecā akreditācijas datu atsaukšanas.
Atsauciet atslēgas, kas vairs netiek izmantotas vai kuru noslēpums varētu būt atklāts.
Nepersonisku integrāciju vajadzībām izmantojiet servisa kontu atslēgas, ja šāds atslēgu veids ir pieejams jūsu organizācijai.

Lappušu dalīšana

People meklēšana atbalsta parametrus limit, cursor, offset un includeTotal. Secīgai pārlūkošanai priekšroku dodiet kursoram, ko atgriezusi iepriekšējā atbilde.

limit pēc noklusējuma ir 50 un pieņem vērtības 1–100.
cursor turpina no iepriekšējās atbildes.
offset izlaiž noteiktu ierakstu skaitu, un pēc noklusējuma tas ir 0.
includeTotal=true pieprasa precīzu filtrēto skaitu; izlaidiet to, ja skaits nav nepieciešams.

Nolasiet objektu pagination, ko atgriež galapunkts. Neaprēķiniet nākamo lappusi pēc saņemto rindu skaita un nekombinējiet neatkarīgi lappušotus pieprasījumus, pašrocīgi kārtojot daļējos rezultātus.

Kļūdas

Dokumentētajām JSON kļūdām ir šāda vispārīgā struktūra:

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

message var būt virkne vai validācijas ziņojumu masīvs.

Statuss	Nozīme	Rīcība
`400`	Nederīgi parametri vai pieprasījuma pamatteksts	Izlabojiet norādītās validācijas kļūdas
`401`	Nesēja pilnvara trūkst, ir nederīga vai beigusies	Vēlreiz apmainiet piekļuves atslēgu un mēģiniet vienreiz atkārtoti
`403`	Akreditācijas datiem trūkst atļaujas vai piekļuves organizācijai	Pārbaudiet atslēgas apjomus un organizācijas kontekstu
`404`	Resurss nepastāv autorizētajā organizācijā	Pārbaudiet resursa ID un organizāciju
`408`	Pieprasījuma noildze	Mēģiniet atkārtoti ar ierobežotu eksponenciālo atkāpi
`429`	Sasniegts ātruma ierobežojums	Gaidiet vismaz tik ilgi, cik norādīts `Retry-After`, ja tas ir
`5xx`	Īslaicīgs pakalpojuma traucējums	Drošus lasīšanas pieprasījumus atkārtojiet ar ierobežotu eksponenciālo atkāpi

Kurētais līgums pašlaik nepublicē vienu universālu skaitlisku ātruma ierobežojumu un negarantē pieprasījuma ID atbildes galveni katrai darbībai. Vēršoties atbalstā, fiksējiet UTC laiku, metodi, ceļu, statusu un attīrītu atbildes pamattekstu. Automātiski neatkārtojiet izveides, rotācijas, atsaukšanas vai dzēšanas darbības, ja darbībai nav skaidri dokumentēta idempotence. Pēc nenoteiktas tīkla kļūmes pārbaudiet resursa pašreizējo stāvokli.

Saderība un novecošana

V1 pēc noklusējuma attīstās tikai papildinot. Klientiem jāignorē nezināmi atbildes lauki. Izmaiņām, kas pārtrauc saderību, nepieciešams dokumentēts migrācijas ceļš; novecojušās darbības paliek atsaucē kopā ar iemeslu, aizstājēju (ja tāds ir) un izbeigšanas datumu migrācijas periodā. Piesaistiet SDK saderīgai galvenajai versijai un pirms jaunināšanas izlasiet tā laidiena piezīmes. Shēmas vienīgo patiesības avotu meklējiet ģenerētajā Public API Reference, nevis pirmās puses lietotnes klientos.

Public API, MCP un tīmekļa lietojumprogramma

Virsma	Izmantošana	Saderības modelis
Public API	Klientu sistēmas, partneri un ārējā automatizācija	Stabili, versionēti resursi
MCP	Ar atļaujām pārvaldīta mijiedarbība ar MI rīkiem	Rīku līgumi un kompakti strukturēti izvaddati
Tīmekļa lietojumprogramma	Cilvēku darbplūsmas Living Security produktā	Lietotnes īpašumā esoši līgumi, kas var mainīties kopā ar lietotāja saskarni

Lai pievienotu MI rīku Living Security, skatiet MCP Integration.

Palīdzības saņemšana

Sazinieties ar Living Security atbalstu, norādot:

Organizāciju un reģionu
SDK nosaukumu un versiju, ja tas tiek izmantots
UTC laika zīmogu, metodi un ceļu
HTTP statusu un attīrītu kļūdas pamattekstu

Nekad neiekļaujiet piekļuves atslēgu noslēpumus, nesēja pilnvaras vai privātus klientu datus.

Publiskais API

Publiskā API atsauce

Pirms sākat

Reģionālie resursdatori

Mantotie resursi

Autentifikācija

TypeScript SDK

Tiešs REST pieprasījums

Piekļuves atslēgas dzīves cikls

Lappušu dalīšana

Kļūdas

Saderība un novecošana

Public API, MCP un tīmekļa lietojumprogramma

Palīdzības saņemšana

Saistītie materiāli

API Access Keys

MCP Integration

Publiskais API

Publiskā API atsauce

​Pirms sākat

​Reģionālie resursdatori

​Mantotie resursi

​Autentifikācija

​TypeScript SDK

​Tiešs REST pieprasījums

​Piekļuves atslēgas dzīves cikls

​Lappušu dalīšana

​Kļūdas

​Saderība un novecošana

​Public API, MCP un tīmekļa lietojumprogramma

​Palīdzības saņemšana

​Saistītie materiāli

API Access Keys

MCP Integration

Pirms sākat

Reģionālie resursdatori

Mantotie resursi

Autentifikācija

TypeScript SDK

Tiešs REST pieprasījums

Piekļuves atslēgas dzīves cikls

Lappušu dalīšana

Kļūdas

Saderība un novecošana

Public API, MCP un tīmekļa lietojumprogramma

Palīdzības saņemšana

Saistītie materiāli