Verouderde Public API

Deze handleiding behandelt bestaande /api/v1-integraties die een API-toegangssleutel inwisselen voor een bearer-token. De referenties en het aanvraagformaat verschillen van die van de /v1 Public API. Begin voor een nieuwe integratie met de API-quickstart en Authenticatie. De nieuwe /v1-API maakt gebruik van API-sleutels voor serviceaccounts of OAuth-toegangstokens.

Voordat u begint

U hebt het volgende nodig:

Toegang tot Living Security die het beheer van API-toegangssleutels toestaat
Een API-toegangssleutel die is aangemaakt onder instellingen → Access Keys
Het eenmalige geheim van de toegangssleutel dat wordt getoond wanneer de referentie wordt aangemaakt
De API-issuer-ID die Living Security samen met uw Public API-referenties heeft verstrekt
De regionale basis-URL voor de organisatie die u integreert
Een server-side runtime en een secretmanager

Geheimen van toegangssleutels mogen niet worden opgenomen in browsercode, mobiele apps, broncodebeheer, client-side omgevingsvariabelen, tickets of gedeelde logbestanden.

Het dialoogvenster Access Keys toont het eenmalige geheim, maar niet de API-issuer-ID. Als Living Security de issuer-ID niet samen met uw Public API-referenties heeft verstrekt, vraagt u deze op bij Living Security Support. De issuer-ID is niet hetzelfde als de ID van de toegangssleutel of de organisatie-ID.

Regionale hosts

Het verouderde contract gebruikt deze regionale /api/v1-productiehosts:

Regio	Basis-URL
VS	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Gebruik de regio die is toegewezen aan de Living Security-organisatie. Schakel niet over naar een andere regio om een autorisatie- of beschikbaarheidsfout te omzeilen.

Verouderde resources

Resource	Ondersteunde bewerkingen
Mensen	Mensen in de organisatie zoeken en het lidmaatschap van een persoon ophalen
API-toegangssleutels	API-toegangssleutels aanmaken, weergeven, roteren en intrekken

Gebruik Developers → Public API Reference voor de volledige lijst met bewerkingen, parameters, aanvragen, antwoorden en schema’s. Als een bewerking daar niet staat, maakt deze momenteel geen deel uit van de Public API.

Authenticatie

Toegang tot de Public API verloopt in twee stappen:

Wissel de geheime toegangssleutel en de API-issuer-ID in voor een kortlevend bearer-token en een organisatie-ID.
Stuur het bearer-token en de organisatie-ID mee met elke API-aanvraag.

De vereiste aanvraagheaders zijn:

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

De organisatieheader moet de organisatie zijn die bij het inwisselen van de toegangssleutel is geretourneerd. Een sleutel geeft geen toegang tot een willekeurige organisatie-ID.

TypeScript SDK

Installeer de huidige hoofdversie:

npm install @livingsecurity/sdk@^1

Wissel vervolgens de sleutel in en configureer de 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,
});

Gebruik de EU-basis-URL voor een EU-organisatie. De inwisseling via de SDK is bedoeld voor server-side Node.js-runtimes.

Directe REST-aanvraag

Als u de inwisseling buiten de SDK uitvoert, stuur dan het bijbehorende bearer-token en de organisatie-ID mee met elke aanvraag:

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-tokens zijn kortlevend. Wissel de toegangssleutel opnieuw in wanneer u een nieuw token nodig hebt, in plaats van een bearer-token als permanente referentie op te slaan.

Levenscyclus van toegangssleutels

Vernoem sleutels naar de integratie of automatisering waartoe ze behoren.
Kies de scopes met de minste rechten die het formulier voor toegangssleutels biedt.
Sla het eenmalige geheim direct op; het kan na het aanmaken of roteren niet meer worden opgehaald.
Roteer een sleutel via instellingen → Access Keys en implementeer de vervangende sleutel voordat u de oude referentie intrekt.
Trek sleutels in die niet meer worden gebruikt of waarvan het geheim mogelijk is blootgesteld.
Gebruik sleutels voor serviceaccounts voor niet-menselijke integraties wanneer dat sleuteltype beschikbaar is voor uw organisatie.

Paginering

Het zoeken naar mensen ondersteunt de parameters limit, cursor, offset en includeTotal. Gebruik bij voorkeur de cursor uit het vorige antwoord voor sequentieel doorlopen.

limit heeft als standaardwaarde 50 en accepteert 1–100.
cursor gaat verder vanaf een eerder antwoord.
offset slaat een aantal records over en heeft als standaardwaarde 0.
includeTotal=true vraagt een exact gefilterd aantal op; laat dit weg wanneer het aantal niet nodig is.

Lees het object pagination dat door het eindpunt wordt geretourneerd. Bereken de volgende pagina niet op basis van het aantal ontvangen rijen en combineer geen onafhankelijk gepagineerde aanvragen om de gedeeltelijke resultaten zelf te sorteren.

Fouten

Gedocumenteerde JSON-fouten hebben over het algemeen de volgende structuur:

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

message kan een string of een array met validatieberichten zijn.

Status	Betekenis	Reactie
`400`	Ongeldige parameters of aanvraagbody	Corrigeer de genoemde validatiefouten
`401`	Bearer-token ontbreekt, is ongeldig of is verlopen	Wissel de toegangssleutel opnieuw in en probeer het één keer opnieuw
`403`	Referentie mist rechten of toegang tot de organisatie	Controleer de sleutelscopes en de organisatiecontext
`404`	Resource bestaat niet in de geautoriseerde organisatie	Controleer de resource-ID en de organisatie
`408`	Time-out van de aanvraag	Probeer het opnieuw met begrensde exponentiële backoff
`429`	Snelheidslimiet bereikt	Wacht minstens zo lang als `Retry-After`, indien aanwezig
`5xx`	Tijdelijke storing van de service	Probeer veilige leesbewerkingen opnieuw met begrensde exponentiële backoff

Het samengestelde contract publiceert momenteel geen universele numerieke snelheidslimiet en garandeert niet voor elke bewerking een response-header met een aanvraag-ID. Leg de UTC-tijd, methode, het pad, de status en de opgeschoonde response-body vast wanneer u support inschakelt. Probeer bewerkingen voor aanmaken, roteren, intrekken of verwijderen niet automatisch opnieuw, tenzij de bewerking expliciet idempotentie documenteert. Controleer de actuele status van de resource na een dubbelzinnige netwerkfout.

Compatibiliteit en beëindiging van ondersteuning

V1 wordt standaard additief doorontwikkeld. Clients moeten onbekende velden in antwoorden negeren. Voor een wijziging die compatibiliteit verbreekt is een gedocumenteerd migratiepad vereist; verouderde bewerkingen blijven tijdens de migratieperiode in de referentie staan, met vermelding van de reden, het vervangende alternatief indien beschikbaar en de einddatum van de ondersteuning. Leg de SDK vast op een compatibele hoofdversie en lees de release notes voordat u een upgrade uitvoert. Beschouw de gegenereerde Public API Reference, en niet de first-party app-clients, als de leidende bron voor het schema.

Public API, MCP en de webapplicatie

Oppervlak	Gebruik voor	Compatibiliteitsmodel
Public API	Klantsystemen, partners en externe automatisering	Stabiele, geversioneerde resources
MCP	AI-toolinteracties met machtigingen	Toolcontracten en compacte gestructureerde uitvoer
Webapplicatie	Menselijke workflows in het Living Security-product	Contracten van de app die met de UI kunnen meeveranderen

Zie MCP-integratie om een AI-tool met Living Security te verbinden.

Hulp krijgen

Neem contact op met Living Security Support en vermeld daarbij:

Organisatie en regio
Naam en versie van de SDK, indien gebruikt
UTC-tijdstempel, methode en pad
HTTP-status en opgeschoonde foutbody

Neem nooit geheimen van toegangssleutels, bearer-tokens of privégegevens van klanten op.

Openbare API

Naslag openbare API

Voordat u begint

Regionale hosts

Verouderde resources

Authenticatie

TypeScript SDK

Directe REST-aanvraag

Levenscyclus van toegangssleutels

Paginering

Fouten

Compatibiliteit en beëindiging van ondersteuning

Public API, MCP en de webapplicatie

Hulp krijgen

Gerelateerd

API-toegangssleutels

MCP-integratie

Openbare API

Naslag openbare API

​Voordat u begint

​Regionale hosts

​Verouderde resources

​Authenticatie

​TypeScript SDK

​Directe REST-aanvraag

​Levenscyclus van toegangssleutels

​Paginering

​Fouten

​Compatibiliteit en beëindiging van ondersteuning

​Public API, MCP en de webapplicatie

​Hulp krijgen

​Gerelateerd

API-toegangssleutels

MCP-integratie

Voordat u begint

Regionale hosts

Verouderde resources

Authenticatie

TypeScript SDK

Directe REST-aanvraag

Levenscyclus van toegangssleutels

Paginering

Fouten

Compatibiliteit en beëindiging van ondersteuning

Public API, MCP en de webapplicatie

Hulp krijgen

Gerelateerd