API-Schnellstart

Erstellen Sie im Developer Hub ein Servicekonto und einen API-Schlüssel und senden Sie anschließend Ihre erste Anfrage. Dieser Schnellstart verwendet die Authentifizierung per API-Schlüssel; ein OAuth-Client ist nicht erforderlich. Siehe Authentifizierung, wenn Ihre Integration kurzlebige OAuth-Zugriffstokens benötigt.

Voraussetzungen

Administratorzugriff auf das Living Security Dashboard.
Der Developer Hub ist unter Einstellungen → Integrationen & Developers → Developer Hub sichtbar.

Zugangsdaten erstellen

Servicekonto erstellen

Öffnen Sie im Developer Hub die Registerkarte Service accounts und erstellen Sie ein Konto. Geben Sie ihm einen aussagekräftigen Namen (zum Beispiel reporting-pipeline) und erteilen Sie die Berechtigungen, die seine Schlüssel verwenden dürfen – für diese Anleitung genügt organization:read.Die Berechtigungen des Kontos bilden die Obergrenze für jeden darunter erstellten Schlüssel: Ein Schlüssel kann nie mehr, als sein Servicekonto erlaubt.

API-Schlüssel erstellen

Öffnen Sie die Detailseite des Servicekontos und erstellen Sie einen Schlüssel. Wählen Sie die Berechtigungen, die dieser Schlüssel benötigt (eine Teilmenge der Berechtigungen des Kontos), sowie eine Gültigkeitsdauer – 30, 90 oder 365 Tage oder einen benutzerdefinierten Zeitraum. Die Gültigkeitsdauer ist verpflichtend.Das Secret des Schlüssels beginnt mit lsk_live_ und wird nur einmal angezeigt. Kopieren Sie es sofort in einen Secret Manager; es kann später nicht erneut abgerufen werden.

Committen Sie API-Schlüssel-Secrets niemals in die Versionsverwaltung und binden Sie sie nicht in clientseitigen Code ein. Jeder, der das Secret besitzt, kann mit den Berechtigungen des Schlüssels handeln.

Region auswählen

Rufen Sie den regionalen /v1-Host auf, der dem Datenspeicherort der Organisation entspricht. Schlüssel authentifizieren sich nur auf diesem Host.

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

Siehe Regionen, wenn Sie nicht sicher sind, welchen Host Sie verwenden sollen. Ein gültiger Schlüssel, der an die andere Region gesendet wird, schlägt mit unauthorized fehl. Verwenden Sie das Regions-Dropdown im folgenden Beispiel, um den Host zu wechseln.

Erste Anfrage senden

Laden Sie LIVING_SECURITY_API_KEY aus Ihrem Secret Manager in die Umgebung des Prozesses, der die Anfrage sendet. Die folgenden Beispiele lesen es aus, ohne ein Secret im Quellcode einzubetten. Installieren Sie für Python zuerst requests.Rufen Sie die API auf, indem Sie das Secret im Passwort- oder im Benutzernamenfeld der HTTP-Basic-Authentifizierung übergeben – beides funktioniert. Clients, die beide Felder ausgefüllt verlangen (etwa der Web-Connector von Power BI), können im jeweils anderen Feld einen Platzhalter wie apikey eintragen.

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())

Eine erfolgreiche Antwort gibt Ihre Organisation zurück:

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"
}

Wenn Sie diese Antwort erhalten, funktionieren Ihre Zugangsdaten. Die Anfrage erscheint zudem innerhalb weniger Augenblicke in der Registerkarte Request logs des Developer Hub.

Bearer-Authentifizierung mit demselben Secret (Authorization: Bearer lsk_live_...) funktioniert ebenfalls. Basic Auth gibt es, damit Tools, die nur Benutzername/Passwort unterstützen – wie der Web-Connector von Power BI – eine Verbindung herstellen können.

So funktioniert die Authentifizierung

Die Zugangsdaten bestimmen die Organisation. /v1-Anfragen enthalten keinen Mandantenselektor: kein Organisations-Pfadsegment und keinen Organisations-Header. Das Senden eines x-organization-id-Headers wird mit invalid_request abgelehnt. Der Host muss weiterhin zur Region dieser Organisation passen. Siehe Regionen.
Berechtigungen werden pro Operation geprüft. Jede /v1-Operation erfordert eine benannte Berechtigung (zum Beispiel erfordert GET /v1/organization organization:read). Einem Schlüssel ohne diese Berechtigung wird ein 403 mit dem Code insufficient_permission zurückgegeben.
Schlüssel laufen ab und können ohne Ausfallzeit rotiert werden. Siehe API-Schlüssel zur Rotation mit einem Überlappungszeitraum.

Fehlerantworten lesen

Jeder /v1-Fehler ist application/problem+json (RFC 9457) mit einem stabilen maschinenlesbaren Code. Eine Anfrage mit fehlenden oder unbekannten Zugangsdaten liefert beispielsweise:

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
}

Verzweigen Sie anhand von code, niemals anhand von detail. Folgen Sie doc_url für die Schritte zur Behebung und geben Sie request_id an, wenn Sie den Support kontaktieren – er stimmt mit dem Antwort-Header Request-Id und den Request logs des Developer Hub überein. Alle Codes finden Sie in der Fehlerreferenz.

Vertragsversionen

Jede Antwort gibt die Vertragsversion, die sie bereitgestellt hat, im Header Living-Security-Version zurück, zusammen mit einem Header Request-Id zur Korrelation. Sie können eine Anfrage per Datum auf eine veröffentlichte Vertragsversion festlegen:

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"

Die Version wird in dieser Reihenfolge aufgelöst: der Anfrage-Header, falls vorhanden, andernfalls der festgelegte Standard des Servicekontos, andernfalls die neueste veröffentlichte Version. Die Anforderung einer Version, die nicht veröffentlicht ist (oder deren Sunset-Datum überschritten ist), liefert ein 400 mit dem Code unsupported_version. Veröffentlichte Versionen und ihre Änderungen sind im API-Änderungsprotokoll aufgeführt.

Fehlerbehebung bei Ihrer ersten Anfrage

Ergebnis	Nächste Maßnahme
`401 unauthorized`	Prüfen Sie das Secret, sein Ablaufdatum und die Region der Organisation. Probieren Sie mit gültigen Zugangsdaten keine anderen Hosts aus.
`403 insufficient_permission`	Erteilen Sie `organization:read` sowohl dem Servicekonto als auch seinem Schlüssel.
`400 unsupported_version`	Wählen Sie eine veröffentlichte Version aus dem Änderungsprotokoll.
`429 rate_limited`	Warten Sie auf `Retry-After`; folgen Sie dem Beispiel für begrenzte Wiederholungsversuche.
Netzwerk-Timeout	Prüfen Sie die Konnektivität und wiederholen Sie diese Leseanfrage innerhalb des Wiederholungsbudgets Ihrer Anwendung.

Folgen Sie bei anderen Fehlern dem doc_url der Antwort. Bewahren Sie Request-Id für den Support auf; geben Sie in einem Ticket niemals den Authorization-Header oder Ihren API-Schlüssel an.

Nächste Schritte

Regionen

Wählen Sie den /v1-Host für die Organisation in den USA oder der EU.

Paginierung

Durchlaufen Sie Listen mit page_token und dem Listen-Envelope.

Ratenbegrenzungen

Verstehen Sie Anfragebudgets und behandeln Sie 429-Antworten.

Fehlerreferenz

Jeder Fehlercode, sein HTTP-Status und die Behebung.

Developer Hub

Verwalten Sie Servicekonten, API-Schlüssel und Request logs.

Entwickler-Hub

Öffentliche API v1

API-v1-Referenz

Voraussetzungen

Zugangsdaten erstellen

So funktioniert die Authentifizierung

Fehlerantworten lesen

Vertragsversionen

Fehlerbehebung bei Ihrer ersten Anfrage

Nächste Schritte

Regionen

Paginierung

Ratenbegrenzungen

Fehlerreferenz

Developer Hub

Entwickler-Hub

Öffentliche API v1

API-v1-Referenz

​Voraussetzungen

​Zugangsdaten erstellen

​So funktioniert die Authentifizierung

​Fehlerantworten lesen

​Vertragsversionen

​Fehlerbehebung bei Ihrer ersten Anfrage

​Nächste Schritte

Regionen

Paginierung

Ratenbegrenzungen

Fehlerreferenz

Developer Hub

Voraussetzungen

Zugangsdaten erstellen

So funktioniert die Authentifizierung

Fehlerantworten lesen

Vertragsversionen

Fehlerbehebung bei Ihrer ersten Anfrage

Nächste Schritte