Vanha Public API

Tämä opas koskee olemassa olevia /api/v1-integraatioita, joissa API-käyttöavain vaihdetaan bearer-tunnukseen. Niiden tunnistetiedot ja pyyntömuoto poikkeavat /v1 Public API:sta. Uuden integraation kohdalla aloita API:n pikaoppaasta ja todennusta käsittelevästä osiosta. Uusi /v1-API käyttää palvelutilin API-avaimia tai OAuth-käyttöoikeustunnuksia.

Ennen aloittamista

Tarvitset seuraavat:

Living Security -käyttöoikeudet, jotka sallivat API-käyttöavainten hallinnan
API-käyttöavain, joka on luotu kohdassa Asetukset → Access Keys
Kertaluonteinen käyttöavaimen salaisuus, joka näytetään tunnistetietoa luotaessa
API-myöntäjän tunnus (issuer ID), jonka Living Security on toimittanut Public API -tunnistetietojesi mukana
Integroitavan organisaation alueellinen perus-URL
Palvelinpuolen ajoympäristö ja salaisuuksien hallintajärjestelmä

Käyttöavainten salaisuuksia ei saa sijoittaa selainkoodiin, mobiilisovelluksiin, versionhallintaan, asiakaspuolen ympäristömuuttujiin, tukipyyntöihin tai jaettuihin lokeihin.

Access Keys -valintaikkuna näyttää kertaluonteisen salaisuuden, mutta ei näytä API-myöntäjän tunnusta. Jos Living Security ei ole toimittanut myöntäjän tunnusta Public API -tunnistetietojesi mukana, pyydä se Living Securityn tuesta. Myöntäjän tunnus ei ole sama kuin käyttöavaimen tunnus tai organisaation tunnus.

Alueelliset isäntäpalvelimet

Vanha rajapintasopimus käyttää seuraavia alueellisia /api/v1-tuotantopalvelimia:

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

Käytä Living Security -organisaatiolle määritettyä aluetta. Älä vaihda aluetta kiertääksesi valtuutus- tai saatavuusvirhettä.

Vanhat resurssit

Resurssi	Tuetut toiminnot
Ihmiset	Organisaation ihmisten haku ja henkilön jäsenyyden noutaminen
API-käyttöavaimet	API-käyttöavainten luominen, listaaminen, kierrättäminen ja mitätöinti

Käytä kohtaa Developers → Public API Reference nähdäksesi täydellisen luettelon toiminnoista, parametreista, pyynnöistä, vastauksista ja skeemoista. Jos toimintoa ei löydy sieltä, se ei tällä hetkellä kuulu Public API:in.

Todennus

Public API -käyttöoikeus muodostuu kahdesta vaiheesta:

Vaihda salainen käyttöavain ja API-myöntäjän tunnus lyhytikäiseen bearer-tunnukseen ja organisaation tunnukseen.
Lähetä bearer-tunnus ja organisaation tunnus jokaisen API-pyynnön mukana.

Vaadittavat pyyntöotsikot ovat:

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

Organisaatio-otsikon on vastattava organisaatiota, jonka käyttöavaimen vaihto palautti. Avain ei oikeuta pääsyyn mihin tahansa organisaation tunnukseen.

TypeScript SDK

Asenna nykyinen pääversio:

npm install @livingsecurity/sdk@^1

Vaihda sitten avain ja määritä 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,
});

Käytä EU-organisaatiolle EU-perus-URL:ia. SDK:n suorittama vaihto on tarkoitettu palvelinpuolen Node.js-ajoympäristöihin.

Suora REST-pyyntö

Jos suoritat vaihdon SDK:n ulkopuolella, lähetä sen bearer-tunnus ja organisaation tunnus jokaisessa pyynnössä:

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-tunnukset ovat lyhytikäisiä. Vaihda käyttöavain uudelleen, kun tarvitset uuden tunnuksen, äläkä säilytä bearer-tunnusta pysyvänä tunnistetietona.

Käyttöavaimen elinkaari

Nimeä avaimet niitä omistavan integraation tai automaation mukaan.
Valitse käyttöavainlomakkeen tarjoamista oikeuksista suppeimmat tarvittavat.
Tallenna kertaluonteinen salaisuus heti; sitä ei voi noutaa luomisen tai kierrättämisen jälkeen.
Kierrätä avain kohdassa Asetukset → Access Keys ja ota korvaava avain käyttöön ennen vanhan tunnistetiedon mitätöintiä.
Mitätöi avaimet, joita ei enää käytetä tai joiden salaisuus on saattanut paljastua.
Käytä palvelutilin avaimia muille kuin ihmiskäyttäjille tarkoitetuissa integraatioissa, kun tämä avaintyyppi on organisaatiosi käytettävissä.

Sivutus

Ihmishaku tukee parametreja limit, cursor, offset ja includeTotal. Käytä peräkkäiseen läpikäyntiin mieluiten edellisen vastauksen palauttamaa kursoria.

limit on oletuksena 50 ja hyväksyy arvot 1–100.
cursor jatkaa edellisen vastauksen kohdasta.
offset ohittaa tietyn määrän tietueita, ja sen oletusarvo on 0.
includeTotal=true pyytää tarkan suodatetun lukumäärän; jätä se pois, jos lukumäärää ei tarvita.

Lue päätepisteen palauttama pagination-objekti. Älä laske seuraavaa sivua vastaanotettujen rivien määrästä äläkä yhdistä erikseen sivutettuja pyyntöjä ja lajittele osatuloksia itse.

Virheet

Dokumentoidut JSON-virheet noudattavat seuraavaa yleistä rakennetta:

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

message voi olla merkkijono tai taulukko validointiviestejä.

Tila	Merkitys	Toimenpide
`400`	Virheelliset parametrit tai pyynnön runko	Korjaa mainitut validointivirheet
`401`	Bearer-tunnus puuttuu, on virheellinen tai vanhentunut	Vaihda käyttöavain uudelleen ja yritä kerran uudelleen
`403`	Tunnistetiedolla ei ole oikeutta tai pääsyä organisaatioon	Tarkista avaimen oikeudet ja organisaatiokonteksti
`404`	Resurssia ei ole valtuutetussa organisaatiossa	Tarkista resurssin tunnus ja organisaatio
`408`	Pyyntö aikakatkaistiin	Yritä uudelleen rajatulla eksponentiaalisella viiveellä
`429`	Pyyntörajoitus saavutettu	Odota vähintään `Retry-After`-arvon mukainen aika, jos se on annettu
`5xx`	Tilapäinen palveluhäiriö	Yritä turvallisia lukupyyntöjä uudelleen rajatulla eksponentiaalisella viiveellä

Kuratoitu rajapintasopimus ei tällä hetkellä julkaise yhtä yleistä numeerista pyyntörajaa eikä takaa pyyntötunnuksen vastausotsikkoa jokaiselle toiminnolle. Kirjaa tukipyyntöä tehdessäsi ylös UTC-aika, metodi, polku, tila ja puhdistettu vastauksen runko. Älä yritä luonti-, kierrätys-, mitätöinti- tai poistotoimintoja automaattisesti uudelleen, ellei toiminnon idempotenssia ole nimenomaisesti dokumentoitu. Tarkista resurssin nykyinen tila epäselvän verkkovirheen jälkeen.

Yhteensopivuus ja käytöstä poistaminen

V1 kehittyy oletuksena lisäävästi. Asiakasohjelmien on ohitettava tuntemattomat vastauskentät. Taaksepäin yhteensopimaton muutos edellyttää dokumentoitua siirtymäpolkua; käytöstä poistuvat toiminnot pysyvät referenssissä siirtymäajan, ja niille ilmoitetaan syy, korvaava toiminto (jos saatavilla) ja päättymispäivä. Kiinnitä SDK yhteensopivaan pääversioon ja tarkista sen julkaisutiedot ennen päivittämistä. Pidä generoitua Public API Referenceä – älä ensimmäisen osapuolen sovellusasiakkaita – skeeman ensisijaisena lähteenä.

Public API, MCP ja verkkosovellus

Rajapinta	Käyttötarkoitus	Yhteensopivuusmalli
Public API	Asiakasjärjestelmät, kumppanit ja ulkoinen automaatio	Vakaat, versioidut resurssit
MCP	Käyttöoikeuksiin perustuva vuorovaikutus tekoälytyökalujen kanssa	Työkalusopimukset ja tiiviit jäsennellyt tulosteet
Verkkosovellus	Ihmisten työnkulut Living Security -tuotteessa	Sovelluksen omistamat sopimukset, jotka voivat muuttua käyttöliittymän mukana

Katso MCP-integraatio, kun haluat yhdistää tekoälytyökalun Living Securityyn.

Avun saaminen

Ota yhteyttä Living Securityn tukeen ja ilmoita seuraavat tiedot:

Organisaatio ja alue
SDK:n nimi ja versio, jos sitä käytetään
UTC-aikaleima, metodi ja polku
HTTP-tila ja puhdistettu virhesanoma

Älä koskaan sisällytä käyttöavainten salaisuuksia, bearer-tunnuksia tai yksityisiä asiakastietoja.

Julkinen rajapinta

Julkisen rajapinnan viite

Ennen aloittamista

Alueelliset isäntäpalvelimet

Vanhat resurssit

Todennus

TypeScript SDK

Suora REST-pyyntö

Käyttöavaimen elinkaari

Sivutus

Virheet

Yhteensopivuus ja käytöstä poistaminen

Public API, MCP ja verkkosovellus

Avun saaminen

Aiheeseen liittyvää

API-käyttöavaimet

MCP-integraatio

Julkinen rajapinta

Julkisen rajapinnan viite

​Ennen aloittamista

​Alueelliset isäntäpalvelimet

​Vanhat resurssit

​Todennus

​TypeScript SDK

​Suora REST-pyyntö

​Käyttöavaimen elinkaari

​Sivutus

​Virheet

​Yhteensopivuus ja käytöstä poistaminen

​Public API, MCP ja verkkosovellus

​Avun saaminen

​Aiheeseen liittyvää

API-käyttöavaimet

MCP-integraatio

Ennen aloittamista

Alueelliset isäntäpalvelimet

Vanhat resurssit

Todennus

TypeScript SDK

Suora REST-pyyntö

Käyttöavaimen elinkaari

Sivutus

Virheet

Yhteensopivuus ja käytöstä poistaminen

Public API, MCP ja verkkosovellus

Avun saaminen

Aiheeseen liittyvää