Legacy Public API

Dieser Leitfaden behandelt bestehende /api/v1-Integrationen, die einen API-Zugriffsschlüssel gegen ein Bearer-Token austauschen. Ihre Anmeldedaten und das Anfrageformat unterscheiden sich von der /v1 Public API. Für eine neue Integration beginnen Sie mit dem API-Schnellstart und der Authentifizierung. Die neue /v1-API verwendet API-Schlüssel von Servicekonten oder OAuth-Zugriffstokens.

Vorbereitung

Sie benötigen:

Living Security-Zugriff, der die Verwaltung von API-Zugriffsschlüsseln erlaubt
Einen API-Zugriffsschlüssel, der unter Einstellungen → Access Keys erstellt wurde
Das einmalig angezeigte Geheimnis des Zugriffsschlüssels, das bei der Erstellung der Anmeldedaten angezeigt wird
Die API-Aussteller-ID, die Living Security Ihnen zusammen mit Ihren Public-API-Anmeldedaten zur Verfügung stellt
Die regionale Basis-URL der Organisation, die Sie anbinden
Eine serverseitige Laufzeitumgebung und einen Secret-Manager

Geheimnisse von Zugriffsschlüsseln dürfen nicht in Browsercode, mobilen Apps, Quellcodeverwaltung, clientseitigen Umgebungsvariablen, Tickets oder gemeinsam genutzten Logs abgelegt werden.

Der Dialog „Access Keys“ zeigt das einmalige Geheimnis an, aber nicht die API-Aussteller-ID. Falls Living Security Ihnen die Aussteller-ID nicht zusammen mit Ihren Public-API-Anmeldedaten mitgeteilt hat, fordern Sie sie beim Living Security Support an. Die Aussteller-ID ist weder die Zugriffsschlüssel-ID noch die Organisations-ID.

Regionale Hosts

Der Legacy-Vertrag verwendet diese regionalen /api/v1-Produktions-Hosts:

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

Verwenden Sie die Region, die der Living Security-Organisation zugewiesen ist. Wechseln Sie die Region nicht, um einen Autorisierungs- oder Verfügbarkeitsfehler zu umgehen.

Legacy-Ressourcen

Ressource	Unterstützte Operationen
Leute	Personen der Organisation suchen und die Mitgliedschaft einer Person abrufen
API-Zugriffsschlüssel	API-Zugriffsschlüssel erstellen, auflisten, rotieren und widerrufen

Die vollständige Liste der Operationen, Parameter, Anfragen, Antworten und Schemas finden Sie unter Developers → Public API Reference. Ist eine Operation dort nicht aufgeführt, ist sie derzeit nicht Teil der Public API.

Authentifizierung

Der Zugriff auf die Public API erfolgt in zwei Schritten:

Tauschen Sie den geheimen Zugriffsschlüssel und die API-Aussteller-ID gegen ein kurzlebiges Bearer-Token und eine Organisations-ID aus.
Senden Sie das Bearer-Token und die Organisations-ID mit jeder API-Anfrage.

Erforderliche Anfrage-Header sind:

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

Der Organisations-Header muss die Organisation enthalten, die beim Austausch des Zugriffsschlüssels zurückgegeben wurde. Ein Schlüssel berechtigt nicht zum Zugriff auf eine beliebige Organisations-ID.

TypeScript SDK

Installieren Sie die aktuelle Hauptversion:

npm install @livingsecurity/sdk@^1

Tauschen Sie anschließend den Schlüssel aus und konfigurieren Sie das 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,
});

Verwenden Sie für eine EU-Organisation die EU-Basis-URL. Der SDK-Austausch ist für serverseitige Node.js-Laufzeitumgebungen vorgesehen.

Direkte REST-Anfrage

Wenn Sie den Austausch außerhalb des SDK durchführen, senden Sie das Bearer-Token und die Organisations-ID mit jeder Anfrage:

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 sind kurzlebig. Tauschen Sie den Zugriffsschlüssel erneut aus, um ein neues Token zu erhalten, anstatt ein Bearer-Token als dauerhafte Anmeldeinformation zu speichern.

Lebenszyklus von Zugriffsschlüsseln

Benennen Sie Schlüssel nach der zugehörigen Integration oder Automatisierung.
Wählen Sie die Bereiche (Scopes) mit den geringsten Berechtigungen, die das Formular für Zugriffsschlüssel anbietet.
Speichern Sie das einmalige Geheimnis sofort; es kann nach der Erstellung oder Rotation nicht erneut abgerufen werden.
Rotieren Sie einen Schlüssel über Einstellungen → Access Keys und stellen Sie den Ersatzschlüssel bereit, bevor Sie die alten Anmeldedaten widerrufen.
Widerrufen Sie Schlüssel, die nicht mehr verwendet werden oder deren Geheimnis möglicherweise offengelegt wurde.
Verwenden Sie für nicht menschliche Integrationen Servicekonto-Schlüssel, sofern dieser Schlüsseltyp für Ihre Organisation verfügbar ist.

Paginierung

Die Leute-Suche unterstützt die Parameter limit, cursor, offset und includeTotal. Verwenden Sie für eine sequenzielle Abfrage bevorzugt den Cursor aus der vorherigen Antwort.

limit hat den Standardwert 50 und akzeptiert 1–100.
cursor setzt die Abfrage ab einer vorherigen Antwort fort.
offset überspringt eine Anzahl von Datensätzen und hat den Standardwert 0.
includeTotal=true fordert eine exakte gefilterte Anzahl an; lassen Sie den Parameter weg, wenn die Anzahl nicht benötigt wird.

Lesen Sie das vom Endpunkt zurückgegebene Objekt pagination. Berechnen Sie die nächste Seite nicht anhand der Anzahl der empfangenen Zeilen, und kombinieren Sie keine unabhängig paginierten Anfragen, um die Teilergebnisse anschließend selbst zu sortieren.

Fehler

Dokumentierte JSON-Fehler haben im Allgemeinen folgende Struktur:

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

message kann eine Zeichenfolge oder ein Array von Validierungsmeldungen sein.

Status	Bedeutung	Reaktion
`400`	Ungültige Parameter oder ungültiger Anfragetext	Korrigieren Sie die genannten Validierungsfehler
`401`	Bearer-Token fehlt, ist ungültig oder abgelaufen	Tauschen Sie den Zugriffsschlüssel erneut aus und wiederholen Sie die Anfrage einmal
`403`	Den Anmeldedaten fehlt die Berechtigung oder der Organisationszugriff	Prüfen Sie die Schlüsselbereiche und den Organisationskontext
`404`	Ressource existiert in der autorisierten Organisation nicht	Überprüfen Sie die Ressourcen-ID und die Organisation
`408`	Zeitüberschreitung bei der Anfrage	Wiederholen Sie die Anfrage mit begrenztem exponentiellem Backoff
`429`	Ratenlimit erreicht	Warten Sie mindestens so lange wie `Retry-After`, sofern vorhanden
`5xx`	Vorübergehender Dienstausfall	Wiederholen Sie sichere Lesezugriffe mit begrenztem exponentiellem Backoff

Der kuratierte Vertrag veröffentlicht derzeit weder ein einheitliches numerisches Ratenlimit noch garantiert er für jede Operation einen Anfrage-ID-Antwort-Header. Halten Sie bei einer Supportanfrage die UTC-Zeit, die Methode, den Pfad, den Status und den bereinigten Antworttext fest. Wiederholen Sie Operationen zum Erstellen, Rotieren, Widerrufen oder Löschen nicht automatisch, es sei denn, die Operation dokumentiert ausdrücklich Idempotenz. Prüfen Sie nach einem unklaren Netzwerkfehler den aktuellen Zustand der Ressource.

Kompatibilität und Einstellung von Funktionen (Deprecation)

V1 wird standardmäßig additiv weiterentwickelt. Clients müssen unbekannte Antwortfelder ignorieren. Eine inkompatible Änderung erfordert einen dokumentierten Migrationspfad; veraltete Operationen bleiben in der Referenz mit Begründung, gegebenenfalls Ersatz und Abschaltdatum während des Migrationszeitraums erhalten. Legen Sie das SDK auf eine kompatible Hauptversion fest und lesen Sie vor einem Upgrade die Versionshinweise. Betrachten Sie die generierte Public API Reference – nicht die Erstanbieter-App-Clients – als maßgebliche Schemaquelle.

Public API, MCP und die Webanwendung

Oberfläche	Verwendung	Kompatibilitätsmodell
Public API	Kundensysteme, Partner und externe Automatisierung	Stabile, versionierte Ressourcen
MCP	Berechtigungsgesteuerte Interaktionen mit KI-Tools	Tool-Verträge und kompakte strukturierte Ausgaben
Webanwendung	Workflows für Menschen im Living Security-Produkt	Von der App verantwortete Verträge, die sich mit der Benutzeroberfläche weiterentwickeln können

Unter MCP-Integration erfahren Sie, wie Sie ein KI-Tool mit Living Security verbinden.

Hilfe erhalten

Wenden Sie sich an den Living Security Support und geben Sie Folgendes an:

Organisation und Region
SDK-Name und -Version, falls verwendet
UTC-Zeitstempel, Methode und Pfad
HTTP-Status und bereinigten Fehlertext

Geben Sie niemals Geheimnisse von Zugriffsschlüsseln, Bearer-Tokens oder private Kundendaten an.

Öffentliche API

Referenz der öffentlichen API

Vorbereitung

Regionale Hosts

Legacy-Ressourcen

Authentifizierung

TypeScript SDK

Direkte REST-Anfrage

Lebenszyklus von Zugriffsschlüsseln

Paginierung

Fehler

Kompatibilität und Einstellung von Funktionen (Deprecation)

Public API, MCP und die Webanwendung

Hilfe erhalten

Weiterführende Informationen

API-Zugriffsschlüssel

MCP-Integration

Öffentliche API

Referenz der öffentlichen API

​Vorbereitung

​Regionale Hosts

​Legacy-Ressourcen

​Authentifizierung

​TypeScript SDK

​Direkte REST-Anfrage

​Lebenszyklus von Zugriffsschlüsseln

​Paginierung

​Fehler

​Kompatibilität und Einstellung von Funktionen (Deprecation)

​Public API, MCP und die Webanwendung

​Hilfe erhalten

​Weiterführende Informationen

API-Zugriffsschlüssel

MCP-Integration

Vorbereitung

Regionale Hosts

Legacy-Ressourcen

Authentifizierung

TypeScript SDK

Direkte REST-Anfrage

Lebenszyklus von Zugriffsschlüsseln

Paginierung

Fehler

Kompatibilität und Einstellung von Funktionen (Deprecation)

Public API, MCP und die Webanwendung

Hilfe erhalten

Weiterführende Informationen