API:n pikaopas

Luo palvelutili ja API-avain Developer Hubissa ja tee sen jälkeen ensimmäinen pyyntösi. Tässä pikaoppaassa käytetään API-avaimella tehtävää todennusta, joten OAuth-asiakasta ei tarvita. Katso Todennus, jos integraatiosi edellyttää lyhytikäisiä OAuth-käyttöoikeustunnuksia.

Edellytykset

Järjestelmänvalvojan käyttöoikeus Living Securityn Kojelautaan.
Developer Hubin tulee näkyä kohdassa Asetukset → Integraatiot & Developers → Developer Hub.

Tunnistetietojen luominen

Luo palvelutili

Avaa Developer Hubissa Service accounts -välilehti ja luo tili. Anna sille kuvaava nimi (esimerkiksi reporting-pipeline) ja myönnä oikeudet, joita sen avaimet saavat käyttää. Tässä oppaassa riittää organization:read.Tilin oikeudet muodostavat ylärajan kaikille sen alle luoduille avaimille: avain ei koskaan voi tehdä enempää kuin sen palvelutili sallii.

Luo API-avain

Avaa palvelutilin tietosivu ja luo avain. Valitse tälle avaimelle tarvittavat oikeudet (tilin oikeuksien osajoukko) ja voimassaoloaika: 30, 90 tai 365 päivää tai mukautettu jakso. Voimassaoloaika on pakollinen.Avaimen salaisuus alkaa merkkijonolla lsk_live_ ja näytetään vain kerran. Kopioi se heti salaisuuksien hallintajärjestelmään, sillä sitä ei voi hakea myöhemmin uudelleen.

Älä koskaan tallenna API-avainten salaisuuksia versionhallintaan äläkä upota niitä asiakaspuolen koodiin. Jokainen, jolla on salaisuus, voi toimia avaimen oikeuksilla.

Valitse alue

Kutsu alueellista /v1-isäntää, joka vastaa organisaation datan sijaintialuetta. Avaimet todennetaan vain kyseisellä isännällä.

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

Katso Alueet, jos et ole varma, mitä isäntää tulee käyttää. Voimassa oleva avain, joka lähetetään toiselle alueelle, epäonnistuu virheellä unauthorized. Vaihda isäntä alla olevan esimerkin aluevalikosta.

Tee ensimmäinen pyyntösi

Lataa LIVING_SECURITY_API_KEY salaisuuksien hallintajärjestelmästäsi pyynnön tekevän prosessin ympäristöön. Alla olevat esimerkit lukevat sen ilman, että salaisuutta upotetaan lähdekoodiin. Asenna Pythonia varten ensin requests.Kutsu API:a siten, että salaisuus annetaan HTTP Basic -todennuksen salasana- tai käyttäjätunnuskentässä. Kumpi tahansa toimii, joten asiakkaat, jotka vaativat molempien kenttien täyttämisen (kuten Power BI:n Web-liitin), voivat syöttää toiseen kenttään paikkamerkin, kuten apikey.

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

Onnistunut vastaus palauttaa organisaatiosi tiedot:

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

Jos saat tämän vastauksen, tunnistetietosi toimivat. Pyyntö näkyy myös Developer Hubin Request logs -välilehdellä hetken kuluttua.

Bearer-todennus samalla salaisuudella (Authorization: Bearer lsk_live_...) toimii myös. Basic-todennus on olemassa, jotta työkalut, jotka tukevat vain käyttäjätunnusta ja salasanaa, kuten Power BI:n Web-liitin, voivat muodostaa yhteyden.

Todennuksen toiminta

Tunnistetieto määrittää organisaation. /v1-pyynnöissä ei ole vuokraajan valitsinta: ei organisaatiota osoittavaa polun osaa eikä organisaatio-otsikkoa. x-organization-id-otsikon lähettäminen hylätään virheellä invalid_request. Isännän on silti vastattava kyseisen organisaation aluetta. Katso Alueet.
Oikeudet tarkistetaan operaatiokohtaisesti. Jokainen /v1-operaatio edellyttää nimettyä oikeutta (esimerkiksi GET /v1/organization edellyttää oikeutta organization:read). Jos avaimelta puuttuu oikeus, se saa vastauksen 403 koodilla insufficient_permission.
Avaimet vanhenevat, ja ne voidaan vaihtaa ilman käyttökatkoa. Katso API-avaimet, jossa kuvataan vaihto päällekkäisellä siirtymäajalla.

Virhevastausten lukeminen

Jokainen /v1-virhe on application/problem+json (RFC 9457) pysyvällä koneluettavalla koodilla. Esimerkiksi pyyntö, jossa tunnistetieto puuttuu tai on tuntematon, palauttaa:

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
}

Haarauta logiikka kentän code perusteella, älä koskaan kentän detail perusteella. Seuraa doc_url ratkaisuohjeita varten, ja liitä request_id mukaan ottaessasi yhteyttä tukeen – se vastaa Request-Id-vastausotsikkoa ja Developer Hubin pyyntölokeja. Koko koodijoukko on virheviitteessä.

Sopimusversiot

Jokainen vastaus palauttaa sen sopimusversion, joka sen tuotti, Living-Security-Version-otsikossa sekä Request-Id-otsikon korrelointia varten. Voit kiinnittää pyynnön julkaistuun sopimusversioon päivämäärän perusteella:

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"

Versio ratkaistaan tässä järjestyksessä: pyyntöotsikko, jos se on annettu, muuten palvelutilin kiinnitetty oletusversio, muuten uusin julkaistu versio. Jos pyydetty versio ei ole julkaistu (tai sen käytöstäpoistopäivä on ohi), vastauksena on 400 koodilla unsupported_version. Julkaistut versiot ja niiden muutokset on lueteltu API:n muutosloki -sivulla.

Ensimmäisen pyynnön vianmääritys

Tulos	Seuraava toimenpide
`401 unauthorized`	Tarkista salaisuus, sen voimassaoloaika ja organisaation alue. Älä kokeile muita isäntiä voimassa olevalla tunnistetiedolla.
`403 insufficient_permission`	Myönnä `organization:read` sekä palvelutilille että sen avaimelle.
`400 unsupported_version`	Valitse julkaistu versio muutosloki-sivulta.
`429 rate_limited`	Odota ajankohtaa `Retry-After` ja noudata rajattua uudelleenyrityksen esimerkkiä.
Verkon aikakatkaisu	Tarkista yhteys ja yritä tätä lukupyyntöä uudelleen sovelluksesi uudelleenyritysbudjetin puitteissa.

Muiden virheiden kohdalla noudata vastauksen kohtaa doc_url. Säilytä Request-Id tukea varten; älä koskaan liitä Authorization-otsikkoa tai API-avaintasi tukipyyntöön.

Seuraavat vaiheet

Alueet

Valitse organisaatiolle US- tai EU-/v1-isäntä.

Sivutus

Selaa luetteloita käyttäen page_token ja luettelokirjekuorta.

Käyttörajat

Ymmärrä pyyntöbudjetit ja käsittele 429-vastaukset.

Virheviite

Kaikki virhekoodit, niiden HTTP-tila ja ratkaisuohjeet.

Developer Hub

Hallitse palvelutilejä, API-avaimia ja pyyntölokeja.

Kehittäjäkeskus

Julkinen rajapinta v1

API v1 -viite

Edellytykset

Tunnistetietojen luominen

Todennuksen toiminta

Virhevastausten lukeminen

Sopimusversiot

Ensimmäisen pyynnön vianmääritys

Seuraavat vaiheet

Alueet

Sivutus

Käyttörajat

Virheviite

Developer Hub

Kehittäjäkeskus

Julkinen rajapinta v1

API v1 -viite

​Edellytykset

​Tunnistetietojen luominen

​Todennuksen toiminta

​Virhevastausten lukeminen

​Sopimusversiot

​Ensimmäisen pyynnön vianmääritys

​Seuraavat vaiheet

Alueet

Sivutus

Käyttörajat

Virheviite

Developer Hub

Edellytykset

Tunnistetietojen luominen

Todennuksen toiminta

Virhevastausten lukeminen

Sopimusversiot

Ensimmäisen pyynnön vianmääritys

Seuraavat vaiheet