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

# Застарілий Public API

> Підтримка наявних інтеграцій /api/v1, які обмінюють ключ доступу API на bearer-токен.

Цей посібник стосується наявних інтеграцій `/api/v1`, які обмінюють ключ доступу API на bearer-токен. Їхні облікові дані та формат запитів відрізняються від Public API `/v1`.

Для нової інтеграції почніть із [короткого посібника з API](/uk/developers/v1/quickstart) та розділу [Автентифікація](/uk/developers/v1/authentication). Новий API `/v1` використовує ключі API сервісного облікового запису або токени доступу OAuth.

## Перед початком роботи

Вам потрібні:

* Доступ до Living Security, який дозволяє керувати ключами доступу API
* Ключ доступу API, створений у розділі **Settings → Access Keys**
* Одноразовий секрет ключа доступу, що відображається під час створення облікових даних
* Ідентифікатор емітента API (API issuer ID), який Living Security надає разом з обліковими даними Public API
* Регіональна базова URL-адреса для організації, яку ви інтегруєте
* Серверне середовище виконання та менеджер секретів

Секрети ключів доступу не можна розміщувати в коді браузера, мобільних застосунках, системі керування версіями, змінних середовища на стороні клієнта, тікетах або спільних журналах.

<Note>
  Діалогове вікно Access Keys показує одноразовий секрет, але не показує
  ідентифікатор емітента API. Якщо Living Security не надала ідентифікатор
  емітента разом з обліковими даними Public API, запросіть його в [службі
  підтримки Living Security](mailto:support@livingsecurity.com). Ідентифікатор
  емітента не є ні ідентифікатором ключа доступу, ні ідентифікатором організації.
</Note>

## Регіональні хости

Застарілий контракт використовує такі регіональні виробничі хости `/api/v1`:

| Регіон | Базова URL-адреса |
| - | - |
| US | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| EU | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Використовуйте регіон, призначений організації в Living Security. Не змінюйте регіон, щоб обійти помилку авторизації чи доступності.

## Застарілі ресурси

| Ресурс | Підтримувані операції |
| - | - |
| **People** | Пошук людей в організації та отримання даних про членство особи |
| **API access keys** | Створення, перегляд списку, ротація та відкликання ключів доступу API |

Повний перелік операцій, параметрів, запитів, відповідей і схем дивіться в **Developers → Public API Reference**. Якщо операції там немає, вона наразі не є частиною Public API.

## Автентифікація

Доступ до Public API складається з двох етапів:

1. Обміняйте секретний ключ доступу та ідентифікатор емітента API на короткоживучий bearer-токен і ідентифікатор організації.
2. Надсилайте bearer-токен та ідентифікатор організації з кожним запитом API.

Обов’язкові заголовки запиту:

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

Заголовок організації має містити організацію, повернуту під час обміну ключа доступу. Ключ не надає доступу до довільного ідентифікатора організації.

### TypeScript SDK

Установіть поточну основну версію:

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

Потім обміняйте ключ і налаштуйте 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,
});
```

Для організації в ЄС використовуйте базову URL-адресу EU. Обмін через SDK призначений для серверних середовищ виконання Node.js.

### Прямий запит REST

Якщо ви виконуєте обмін поза SDK, надсилайте отриманий bearer-токен та ідентифікатор організації з кожним запитом:

```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-токени короткоживучі. Для отримання нового токена знову обмінюйте ключ доступу, а не зберігайте bearer-токен як постійні облікові дані.

## Життєвий цикл ключа доступу

* Називайте ключі за назвою інтеграції або автоматизації, якій вони належать.
* Обирайте найменш привілейовані області доступу, доступні у формі ключа доступу.
* Одразу збережіть одноразовий секрет: його неможливо отримати після створення чи ротації.
* Виконуйте ротацію ключа в **Settings → Access Keys** і розгорніть новий ключ до відкликання старих облікових даних.
* Відкликайте ключі, які більше не використовуються або секрет яких міг бути розкритий.
* Для нелюдських інтеграцій використовуйте ключі сервісного облікового запису, якщо цей тип ключа доступний вашій організації.

## Пагінація

Пошук людей підтримує параметри `limit`, `cursor`, `offset` і `includeTotal`. Для послідовного обходу краще використовувати курсор із попередньої відповіді.

* `limit` за замовчуванням дорівнює 50 і приймає значення 1–100.
* `cursor` продовжує з попередньої відповіді.
* `offset` пропускає вказану кількість записів; за замовчуванням 0.
* `includeTotal=true` запитує точну кількість відфільтрованих записів; пропускайте його, якщо кількість не потрібна.

Зчитуйте об’єкт `pagination`, який повертає кінцева точка. Не обчислюйте наступну сторінку за кількістю отриманих рядків і не поєднуйте незалежно розбиті на сторінки запити, самостійно сортуючи часткові результати.

## Помилки

Задокументовані помилки JSON мають таку загальну структуру:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

`message` може бути рядком або масивом повідомлень про помилки валідації.

| Статус | Значення | Дія |
| - | - | - |
| `400` | Недійсні параметри або тіло запиту | Виправте зазначені помилки валідації |
| `401` | Bearer-токен відсутній, недійсний або термін його дії минув | Знову обміняйте ключ доступу й повторіть запит один раз |
| `403` | Облікові дані не мають дозволу або доступу до організації | Перевірте області доступу ключа та контекст організації |
| `404` | Ресурс не існує в авторизованій організації | Перевірте ідентифікатор ресурсу та організацію |
| `408` | Час очікування запиту минув | Повторіть запит з обмеженою експоненційною затримкою |
| `429` | Досягнуто ліміт запитів | Зачекайте щонайменше стільки, скільки вказано в `Retry-After`, якщо він присутній |
| `5xx` | Тимчасовий збій сервісу | Повторюйте безпечні операції читання з обмеженою експоненційною затримкою |

Відредагований контракт наразі не публікує єдиного універсального числового ліміту запитів і не гарантує наявності заголовка відповіді з ідентифікатором запиту для кожної операції. Звертаючись до служби підтримки, зазначайте час за UTC, метод, шлях, статус і очищене тіло відповіді.

Не повторюйте автоматично операції створення, ротації, відкликання чи видалення, якщо для операції явно не задокументовано ідемпотентність. Після неоднозначного збою мережі перевіряйте поточний стан ресурсу.

## Сумісність і застарівання

V1 за замовчуванням розвивається лише шляхом додавання. Клієнти повинні ігнорувати невідомі поля відповіді. Критична зміна вимагає задокументованого шляху міграції; застарілі операції залишаються в довіднику із зазначенням причини, заміни (за наявності) та дати припинення підтримки протягом періоду міграції.

Закріпіть SDK за сумісною основною версією та перегляньте примітки до випуску перед оновленням. Вважайте джерелом істини для схем згенерований Public API Reference, а не власні клієнти застосунку.

## Public API, MCP і вебзастосунок

| Поверхня | Призначення | Модель сумісності |
| - | - | - |
| **Public API** | Системи клієнтів, партнери та зовнішня автоматизація | Стабільні ресурси з версіями |
| **MCP** | Взаємодія з AI-інструментами з урахуванням дозволів | Контракти інструментів і компактні структуровані результати |
| **Web application** | Робочі процеси користувачів у продукті Living Security | Контракти, що належать застосунку й можуть змінюватися разом з UI |

Щоб підключити AI-інструмент до Living Security, дивіться розділ [Інтеграція MCP](/uk/integrations/mcp).

## Отримання допомоги

Звертайтеся до [служби підтримки Living Security](mailto:support@livingsecurity.com), надавши:

* Організацію та регіон
* Назву й версію SDK, якщо його використовуєте
* Часову мітку UTC, метод і шлях
* Статус HTTP і очищене тіло помилки

Ніколи не включайте секрети ключів доступу, bearer-токени або приватні дані клієнтів.

## Пов’язані матеріали

<CardGroup cols={2}>
  <Card title="API Access Keys" icon="key" href="/uk/integrations/api-keys">
    Створення, ротація та відкликання облікових даних API.
  </Card>

  <Card title="MCP Integration" icon="robot" href="/uk/integrations/mcp">
    Підключення підтримуваних AI-інструментів через Model Context Protocol.
  </Card>
</CardGroup>


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