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

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

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

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

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

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

Діалогове вікно Access Keys показує одноразовий секрет, але не показує ідентифікатор емітента API. Якщо Living Security не надала ідентифікатор емітента разом з обліковими даними Public API, запросіть його в службі підтримки Living Security. Ідентифікатор емітента не є ні ідентифікатором ключа доступу, ні ідентифікатором організації.

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

Застарілий контракт використовує такі регіональні виробничі хости /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 складається з двох етапів:

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

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

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

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

TypeScript SDK

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

npm install @livingsecurity/sdk@^1

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

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

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

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

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 мають таку загальну структуру:

{
  "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.

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

Звертайтеся до служби підтримки Living Security, надавши:

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

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

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

API Access Keys

Створення, ротація та відкликання облікових даних API.

MCP Integration

Підключення підтримуваних AI-інструментів через Model Context Protocol.

Публічний API

Довідник з публічного API

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

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

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

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

TypeScript SDK

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

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

Пагінація

Помилки

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

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

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

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

API Access Keys

MCP Integration

Публічний API

Довідник з публічного API

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

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

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

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

​TypeScript SDK

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

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

​Пагінація

​Помилки

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

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

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

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

API Access Keys

MCP Integration

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

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

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

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

TypeScript SDK

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

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

Пагінація

Помилки

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

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

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

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