API-quickstart

Maak een serviceaccount en een API-sleutel aan in de Developer Hub en doe vervolgens uw eerste aanvraag. Deze quickstart maakt gebruik van authenticatie met een API-sleutel; u hebt geen OAuth-client nodig. Raadpleeg Authenticatie als uw integratie kortlevende OAuth-toegangstokens vereist.

Vereisten

Beheerderstoegang tot het Living Security Dashboard.
De Developer Hub is zichtbaar onder Instellingen → Integraties & Developers → Developer Hub.

Inloggegevens aanmaken

Een serviceaccount aanmaken

Open in de Developer Hub het tabblad Service accounts en maak een account aan. Geef het een beschrijvende naam (bijvoorbeeld reporting-pipeline) en verleen de machtigingen die de bijbehorende sleutels mogen gebruiken — voor deze handleiding is organization:read voldoende.De machtigingen van het account vormen het maximum voor elke sleutel die eronder wordt aangemaakt: een sleutel kan nooit meer dan wat het serviceaccount toestaat.

Een API-sleutel aanmaken

Open de detailpagina van het serviceaccount en maak een sleutel aan. Kies de machtigingen die deze specifieke sleutel nodig heeft (een subset van die van het account) en een vervaldatum — 30, 90 of 365 dagen, of een aangepaste periode. Een vervaldatum is verplicht.Het geheim van de sleutel begint met lsk_live_ en wordt één keer getoond. Kopieer het direct naar een secretmanager; het kan later niet meer worden opgehaald.

Commit geheimen van API-sleutels nooit naar versiebeheer en sluit ze niet in in code aan de clientzijde. Iedereen die over het geheim beschikt, kan handelen met de machtigingen van de sleutel.

Uw regio kiezen

Roep de regionale /v1-host aan die overeenkomt met de dataresidentie van de organisatie. Sleutels authenticeren alleen op die host.

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

Raadpleeg Regio’s als u niet zeker weet welke host u moet gebruiken. Een geldige sleutel die naar de andere regio wordt verzonden, mislukt met unauthorized. Gebruik de regiodropdown bij het onderstaande voorbeeld om van host te wisselen.

Uw eerste aanvraag doen

Laad LIVING_SECURITY_API_KEY vanuit uw secretmanager in de omgeving van het proces dat de aanvraag doet. De onderstaande voorbeelden lezen het uit zonder een geheim in de broncode op te nemen. Installeer voor Python eerst requests.Roep de API aan met het geheim in het wachtwoord- of gebruikersnaamveld van HTTP Basic-authenticatie — beide werken, zodat clients die vereisen dat beide velden zijn ingevuld (zoals de Web-connector van Power BI) in het andere veld een plaatshouder zoals apikey kunnen plaatsen.

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

Een geslaagde respons retourneert uw organisatie:

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

Als u deze respons ontvangt, werken uw inloggegevens. De aanvraag verschijnt binnen enkele ogenblikken ook op het tabblad Request logs van de Developer Hub.

Bearer-authenticatie met hetzelfde geheim (Authorization: Bearer lsk_live_...) werkt ook. Basic-authenticatie bestaat zodat tools die alleen gebruikersnaam/wachtwoord ondersteunen — zoals de Web-connector van Power BI — verbinding kunnen maken.

Hoe authenticatie werkt

De inloggegevens bepalen de organisatie. /v1-aanvragen bevatten geen tenantselector: geen organisatiepadsegment en geen organisatieheader. Het verzenden van een x-organization-id-header wordt geweigerd met invalid_request. De host moet nog steeds overeenkomen met de regio van die organisatie. Zie Regio’s.
Machtigingen worden per bewerking gecontroleerd. Elke /v1-bewerking vereist een benoemde machtiging (GET /v1/organization vereist bijvoorbeeld organization:read). Een sleutel zonder de machtiging krijgt een 403 met code insufficient_permission.
Sleutels verlopen en kunnen zonder downtime worden geroteerd. Zie API-sleutels voor rotatie met een overlapperiode.

Foutresponsen lezen

Elke /v1-fout is application/problem+json (RFC 9457) met een stabiele machinecode. Een aanvraag met ontbrekende of onbekende inloggegevens retourneert bijvoorbeeld:

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
}

Vertak op basis van code, nooit op basis van detail. Volg doc_url voor de oplossingsstappen en vermeld request_id wanneer u contact opneemt met support — het komt overeen met de Request-Id-responsheader en de aanvraaglogboeken van de Developer Hub. De volledige set codes vindt u in de foutreferentie.

Contractversies

Elke respons geeft de contractversie waarmee de aanvraag is afgehandeld terug in de Living-Security-Version-header, naast een Request-Id-header voor correlatie. U kunt een aanvraag vastzetten op een gepubliceerde contractversie op datum:

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"

De versie wordt in deze volgorde bepaald: de aanvraagheader indien aanwezig, anders de vastgezette standaardversie van het serviceaccount, anders de nieuwste gepubliceerde versie. Het aanvragen van een versie die niet is gepubliceerd (of de einddatum heeft overschreden) retourneert een 400 met code unsupported_version. Gepubliceerde versies en hun wijzigingen staan in de API-changelog.

Problemen met uw eerste aanvraag oplossen

Resultaat	Volgende actie
`401 unauthorized`	Controleer het geheim, de vervaldatum en de regio van de organisatie. Probeer geen andere hosts met actieve inloggegevens.
`403 insufficient_permission`	Verleen `organization:read` aan zowel het serviceaccount als de bijbehorende sleutel.
`400 unsupported_version`	Kies een gepubliceerde versie uit de changelog.
`429 rate_limited`	Wacht op `Retry-After`; volg het voorbeeld van begrensd opnieuw proberen.
Netwerktime-out	Controleer de connectiviteit en probeer deze leesaanvraag opnieuw binnen het retrybudget van uw applicatie.

Volg voor andere fouten de doc_url van de respons. Bewaar de Request-Id voor support; neem nooit de Authorization-header of uw API-sleutel op in een ticket.

Volgende stappen

Regio's

Kies de /v1-host voor de VS of de EU voor de organisatie.

Paginering

Doorloop lijsten met page_token en de lijstenvelop.

Rate limits

Begrijp aanvraagbudgetten en verwerk 429-responsen.

Foutreferentie

Elke foutcode, de bijbehorende HTTP-status en hoe u deze oplost.

Developer Hub

Beheer serviceaccounts, API-sleutels en aanvraaglogboeken.

Ontwikkelaarshub

Openbare API v1

API v1-naslag

Vereisten

Inloggegevens aanmaken

Hoe authenticatie werkt

Foutresponsen lezen

Contractversies

Problemen met uw eerste aanvraag oplossen

Volgende stappen

Regio's

Paginering

Rate limits

Foutreferentie

Developer Hub

Ontwikkelaarshub

Openbare API v1

API v1-naslag

​Vereisten

​Inloggegevens aanmaken

​Hoe authenticatie werkt

​Foutresponsen lezen

​Contractversies

​Problemen met uw eerste aanvraag oplossen

​Volgende stappen

Regio's

Paginering

Rate limits

Foutreferentie

Developer Hub

Vereisten

Inloggegevens aanmaken

Hoe authenticatie werkt

Foutresponsen lezen

Contractversies

Problemen met uw eerste aanvraag oplossen

Volgende stappen