> ## Documentation Index > Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt > Use this file to discover all available pages before exploring further. # API:n pikaopas > Luo palvelutili ja API-avain Developer Hubissa, todenna Basic-todennuksella ja tee ensimmäinen pyyntösi Living Security Public API:in. 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](/fi/developers/v1/authentication), 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 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. 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. 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](/fi/developers/v1/regions), 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. 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`. ```bash cURL theme={null} 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" ``` ```bash cURL (key as username) theme={null} 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" ``` ```python Python theme={null} 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: ```json Response theme={null} { "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](/fi/developers/v1/regions). * **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](/fi/developers/developer-hub/api-keys), jossa kuvataan vaihto päällekkäisellä siirtymäajalla. ## Virhevastausten lukeminen Jokainen `/v1`-virhe on `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) pysyvällä koneluettavalla koodilla. Esimerkiksi pyyntö, jossa tunnistetieto puuttuu tai on tuntematon, palauttaa: ```json 401 Unauthorized theme={null} { "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ä](/fi/developers/v1/errors/overview). ## 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: ```bash cURL theme={null} 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](/fi/developers/v1/changelog) -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](/fi/developers/v1/changelog)-sivulta. | | `429 rate_limited` | Odota ajankohtaa `Retry-After` ja noudata [rajattua uudelleenyrityksen esimerkkiä](/fi/developers/v1/rate-limits). | | 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 Valitse organisaatiolle US- tai EU-`/v1`-isäntä. Selaa luetteloita käyttäen `page_token` ja luettelokirjekuorta. Ymmärrä pyyntöbudjetit ja käsittele `429`-vastaukset. Kaikki virhekoodit, niiden HTTP-tila ja ratkaisuohjeet. Hallitse palvelutilejä, API-avaimia ja pyyntölokeja. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.