Äldre offentligt API

Den här guiden gäller befintliga /api/v1-integrationer som byter en API-åtkomstnyckel mot en bearer-token. Deras autentiseringsuppgifter och begärandeformat skiljer sig från det offentliga /v1-API:et. För en ny integration bör du börja med API-snabbstarten och Autentisering. Det nya /v1-API:et använder API-nycklar för tjänstkonton eller OAuth-åtkomsttokens.

Innan du börjar

Du behöver:

Åtkomst till Living Security som tillåter hantering av API-åtkomstnycklar
En API-åtkomstnyckel som skapats under Inställningar → Access Keys
Den engångshemlighet för åtkomstnyckeln som visas när autentiseringsuppgiften skapas
API-utfärdar-ID:t som Living Security har tillhandahållit tillsammans med dina autentiseringsuppgifter för det offentliga API:et
Den regionala bas-URL:en för den organisation som du integrerar
En körmiljö på serversidan och en hemlighetshanterare

Hemligheter för åtkomstnycklar får inte placeras i webbläsarkod, mobilappar, källkodshantering, miljövariabler på klientsidan, ärenden eller delade loggar.

Dialogrutan Access Keys visar engångshemligheten, men den visar inte API-utfärdar-ID:t. Om Living Security inte har tillhandahållit utfärdar-ID:t tillsammans med dina autentiseringsuppgifter för det offentliga API:et ska du begära det från Living Security Support. Utfärdar-ID:t är inte detsamma som åtkomstnyckelns ID eller organisations-ID:t.

Regionala värdar

Det äldre avtalet använder dessa regionala produktionsvärdar för /api/v1:

Region	Bas-URL
USA	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Använd den region som är tilldelad Living Security-organisationen. Byt inte region för att kringgå ett behörighets- eller tillgänglighetsfel.

Äldre resurser

Resurs	Operationer som stöds
Människor	Söka efter personer i organisationen och hämta en persons medlemskap
API-åtkomstnycklar	Skapa, lista, rotera och återkalla API-åtkomstnycklar

Använd Developers → Public API Reference för den fullständiga listan över operationer, parametrar, begäranden, svar och scheman. Om en operation inte finns där är den för närvarande inte en del av det offentliga API:et.

Autentisering

Åtkomst till det offentliga API:et sker i två steg:

Byt den hemliga åtkomstnyckeln och API-utfärdar-ID:t mot en kortlivad bearer-token och ett organisations-ID.
Skicka bearer-token och organisations-ID med varje API-begäran.

De obligatoriska begärandehuvudena är:

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

Organisationshuvudet måste innehålla den organisation som returneras vid utbytet av åtkomstnyckeln. En nyckel ger inte behörighet till ett godtyckligt organisations-ID.

TypeScript SDK

Installera den aktuella huvudversionen:

npm install @livingsecurity/sdk@^1

Byt sedan nyckeln och konfigurera SDK:t:

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

Använd EU-bas-URL:en för en EU-organisation. SDK-utbytet är avsett för Node.js-körmiljöer på serversidan.

Direkt REST-begäran

Om du utför utbytet utanför SDK:t ska du skicka dess bearer-token och organisations-ID med varje begäran:

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"

Bearer-token är kortlivade. Byt åtkomstnyckeln på nytt när du behöver en ny token, i stället för att spara en bearer-token som en permanent autentiseringsuppgift.

Livscykel för åtkomstnycklar

Namnge nycklar efter den integration eller automatisering som äger dem.
Välj de minst privilegierade behörighetsomfång som åtkomstnyckelformuläret erbjuder.
Spara engångshemligheten direkt; den kan inte hämtas efter att nyckeln har skapats eller roterats.
Rotera en nyckel via Inställningar → Access Keys och distribuera ersättningen innan du återkallar den gamla autentiseringsuppgiften.
Återkalla nycklar som inte längre används eller vars hemlighet kan ha exponerats.
Använd nycklar för tjänstkonton för integrationer som inte är mänskliga när den nyckeltypen är tillgänglig för din organisation.

Paginering

Personsökningen stöder parametrarna limit, cursor, offset och includeTotal. Använd helst markören från det föregående svaret för sekventiell genomgång.

limit är som standard 50 och accepterar 1–100.
cursor fortsätter från ett tidigare svar.
offset hoppar över ett antal poster och är som standard 0.
includeTotal=true begär ett exakt filtrerat antal; utelämna den när antalet inte behövs.

Läs objektet pagination som returneras av slutpunkten. Beräkna inte nästa sida utifrån antalet mottagna rader, och kombinera inte oberoende paginerade begäranden för att sedan själv sortera de partiella resultaten.

Fel

Dokumenterade JSON-fel har följande allmänna form:

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

message kan vara en sträng eller en array med valideringsmeddelanden.

Status	Betydelse	Åtgärd
`400`	Ogiltiga parametrar eller ogiltig begärandetext	Åtgärda de angivna valideringsfelen
`401`	Bearer-token saknas, är ogiltig eller har gått ut	Byt åtkomstnyckeln på nytt och försök igen en gång
`403`	Autentiseringsuppgiften saknar behörighet eller organisationsåtkomst	Kontrollera nyckelns behörighetsomfång och organisationskontext
`404`	Resursen finns inte i den behöriga organisationen	Verifiera resurs-ID och organisation
`408`	Begäran översteg tidsgränsen	Försök igen med begränsad exponentiell backoff
`429`	Hastighetsgränsen har nåtts	Vänta minst lika länge som `Retry-After`, när den finns
`5xx`	Tillfälligt tjänstefel	Försök igen med säkra läsningar med begränsad exponentiell backoff

Det kuraterade avtalet publicerar för närvarande ingen universell numerisk hastighetsgräns och garanterar inte något svarshuvud med begärans-ID för varje operation. Notera UTC-tid, metod, sökväg, status och det sanerade svarsinnehållet när du kontaktar supporten. Försök inte automatiskt igen med åtgärder för att skapa, rotera, återkalla eller ta bort om inte operationen uttryckligen dokumenterar idempotens. Kontrollera resursens aktuella tillstånd efter ett oklart nätverksfel.

Kompatibilitet och utfasning

V1 utvecklas som standard additivt. Klienter måste ignorera okända svarsfält. En ändring som bryter kompatibiliteten kräver en dokumenterad migreringsväg; utfasade operationer finns kvar i referensen med orsak, ersättning när sådan finns och slutdatum under migreringsperioden. Fäst SDK:t vid en kompatibel huvudversion och läs dess versionsinformation innan du uppgraderar. Betrakta den genererade Public API Reference – inte förstapartsappklienter – som den auktoritativa schemakällan.

Offentligt API, MCP och webbapplikationen

Yta	Används för	Kompatibilitetsmodell
Offentligt API	Kundsystem, partner och extern automatisering	Stabila, versionshanterade resurser
MCP	Behörighetsstyrda interaktioner med AI-verktyg	Verktygsavtal och kompakta strukturerade utdata
Webbapplikation	Mänskliga arbetsflöden i produkten Living Security	Appägda avtal som kan utvecklas tillsammans med gränssnittet

Se MCP-integration för att ansluta ett AI-verktyg till Living Security.

Få hjälp

Kontakta Living Security Support med:

Organisation och region
SDK:ts namn och version, om det används
UTC-tidsstämpel, metod och sökväg
HTTP-status och sanerat felinnehåll

Ta aldrig med hemligheter för åtkomstnycklar, bearer-token eller privata kunddata.

Publikt API

Referens för publikt API

Innan du börjar

Regionala värdar

Äldre resurser

Autentisering

TypeScript SDK

Direkt REST-begäran

Livscykel för åtkomstnycklar

Paginering

Fel

Kompatibilitet och utfasning

Offentligt API, MCP och webbapplikationen

Få hjälp

Relaterat

API-åtkomstnycklar

MCP-integration

Publikt API

Referens för publikt API

​Innan du börjar

​Regionala värdar

​Äldre resurser

​Autentisering

​TypeScript SDK

​Direkt REST-begäran

​Livscykel för åtkomstnycklar

​Paginering

​Fel

​Kompatibilitet och utfasning

​Offentligt API, MCP och webbapplikationen

​Få hjälp

​Relaterat

API-åtkomstnycklar

MCP-integration

Innan du börjar

Regionala värdar

Äldre resurser

Autentisering

TypeScript SDK

Direkt REST-begäran

Livscykel för åtkomstnycklar

Paginering

Fel

Kompatibilitet och utfasning

Offentligt API, MCP och webbapplikationen

Få hjälp

Relaterat