> ## 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.

# Vanha Public API

> Ylläpidä olemassa olevia /api/v1-integraatioita, joissa API-käyttöavain vaihdetaan bearer-tunnukseen.

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](/fi/developers/v1/quickstart) ja [todennusta käsittelevästä osiosta](/fi/developers/v1/authentication). 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.

<Note>
  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](mailto:support@livingsecurity.com). Myöntäjän
  tunnus ei ole sama kuin käyttöavaimen tunnus tai organisaation tunnus.
</Note>

## 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:

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

Vaadittavat pyyntöotsikot ovat:

```http theme={null}
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:

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

Vaihda sitten avain ja määritä SDK:

```typescript theme={null}
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ä:

```bash theme={null}
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:

```json theme={null}
{
  "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](/fi/integrations/mcp), kun haluat yhdistää tekoälytyökalun Living Securityyn.

## Avun saaminen

Ota yhteyttä [Living Securityn tukeen](mailto:support@livingsecurity.com) 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.

## Aiheeseen liittyvää

<CardGroup cols={2}>
  <Card title="API-käyttöavaimet" icon="key" href="/fi/integrations/api-keys">
    Luo, kierrätä ja mitätöi API-tunnistetietoja.
  </Card>

  <Card title="MCP-integraatio" icon="robot" href="/fi/integrations/mcp">
    Yhdistä tuetut tekoälytyökalut Model Context Protocolin kautta.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.