Устаревший общедоступный API

Это руководство описывает существующие интеграции /api/v1, в которых ключ доступа к API обменивается на токен-носитель (bearer token). Их учётные данные и формат запросов отличаются от общедоступного API /v1. Для новой интеграции начните с краткого руководства по API и раздела Аутентификация. Новый API /v1 использует ключи API сервисных учётных записей или токены доступа OAuth.

Перед началом работы

Вам потребуется:

доступ к Living Security, позволяющий управлять ключами доступа к API;
ключ доступа к API, созданный в разделе Настройки → Access Keys;
одноразовый секрет ключа доступа, отображаемый при создании учётных данных;
идентификатор издателя API (API issuer ID), предоставленный компанией Living Security вместе с учётными данными общедоступного API;
региональный базовый URL для организации, которую вы интегрируете;
серверная среда выполнения и менеджер секретов.

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

В диалоговом окне Access Keys отображается одноразовый секрет, но не отображается идентификатор издателя API. Если компания Living Security не предоставила идентификатор издателя вместе с учётными данными общедоступного 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. Не меняйте регион, чтобы обойти ошибку авторизации или доступности.

Устаревшие ресурсы

Ресурс	Поддерживаемые операции
Люди	Поиск людей в организации и получение сведений о членстве человека
Ключи доступа к API	Создание, просмотр списка, ротация и отзыв ключей доступа к API

Полный список операций, параметров, запросов, ответов и схем приведён в разделе Developers → Public API Reference. Если операции там нет, она в настоящее время не входит в общедоступный API.

Аутентификация

Доступ к общедоступному API состоит из двух этапов:

Обменяйте секретный ключ доступа и идентификатор издателя API на краткосрочный токен-носитель и идентификатор организации.
Передавайте токен-носитель и идентификатор организации с каждым запросом к 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,
});

Для организации в регионе EU используйте базовый URL для EU. Обмен через SDK предназначен для серверных сред выполнения Node.js.

Прямой REST-запрос

Если вы выполняете обмен вне SDK, передавайте полученный токен-носитель и идентификатор организации в каждом запросе:

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"

Токены-носители являются краткосрочными. Для получения нового токена повторно обменивайте ключ доступа, а не сохраняйте токен-носитель как постоянные учётные данные.

Жизненный цикл ключа доступа

Называйте ключи по имени интеграции или автоматизации, которой они принадлежат.
Выбирайте минимально необходимые области действия (scopes), предлагаемые в форме ключа доступа.
Сразу сохраняйте одноразовый секрет: после создания или ротации его невозможно получить повторно.
Выполняйте ротацию ключа в разделе Настройки → 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`	Токен-носитель отсутствует, недействителен или истёк	Повторно обменяйте ключ доступа и повторите запрос один раз
`403`	У учётных данных нет разрешения или доступа к организации	Проверьте области действия ключа и контекст организации
`404`	Ресурс не существует в авторизованной организации	Проверьте идентификатор ресурса и организацию
`408`	Время ожидания запроса истекло	Повторите запрос с ограниченной экспоненциальной задержкой
`429`	Достигнут лимит запросов	Подождите не меньше времени, указанного в `Retry-After`, если он присутствует
`5xx`	Временный сбой службы	Повторяйте безопасные операции чтения с ограниченной экспоненциальной задержкой

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

Совместимость и прекращение поддержки

V1 по умолчанию развивается аддитивно. Клиенты должны игнорировать неизвестные поля ответа. Для критического изменения требуется задокументированный путь миграции; устаревшие операции остаются в справочнике с указанием причины, замены (при наличии) и даты прекращения поддержки на период миграции. Зафиксируйте версию SDK в пределах совместимой основной версии и перед обновлением изучите примечания к выпуску. Источником истины о схеме считайте сформированный справочник Public API Reference, а не собственные клиентские приложения производителя.

Общедоступный API, MCP и веб-приложение

Поверхность	Назначение	Модель совместимости
Общедоступный API	Системы клиентов, партнёры и внешняя автоматизация	Стабильные ресурсы с версионированием
MCP	Взаимодействие с ИИ-инструментами с учётом разрешений	Контракты инструментов и компактные структурированные результаты
Веб-приложение	Рабочие процессы пользователей в продукте Living Security	Контракты, принадлежащие приложению, которые могут меняться вместе с интерфейсом

О подключении ИИ-инструмента к Living Security см. в разделе Интеграция MCP.

Получение помощи

Обратитесь в службу поддержки Living Security и укажите:

организацию и регион;
название и версию SDK, если он используется;
временную метку в UTC, метод и путь;
HTTP-статус и очищенное тело ошибки.

Никогда не включайте секреты ключей доступа, токены-носители или закрытые данные клиентов.

См. также

Ключи доступа к API

Создание, ротация и отзыв учётных данных API.

Интеграция MCP

Подключение поддерживаемых ИИ-инструментов через Model Context Protocol.

Публичный API

Справочник по публичному API

Устаревший общедоступный API

Перед началом работы

Региональные узлы

Устаревшие ресурсы

Аутентификация

TypeScript SDK

Прямой REST-запрос

Жизненный цикл ключа доступа

Постраничная навигация

Ошибки

Совместимость и прекращение поддержки

Общедоступный API, MCP и веб-приложение

Получение помощи

См. также

Ключи доступа к API

Интеграция MCP

Публичный API

Справочник по публичному API

​Перед началом работы

​Региональные узлы

​Устаревшие ресурсы

​Аутентификация

​TypeScript SDK

​Прямой REST-запрос

​Жизненный цикл ключа доступа

​Постраничная навигация

​Ошибки

​Совместимость и прекращение поддержки

​Общедоступный API, MCP и веб-приложение

​Получение помощи

​См. также

Ключи доступа к API

Интеграция MCP

Перед началом работы

Региональные узлы

Устаревшие ресурсы

Аутентификация

TypeScript SDK

Прямой REST-запрос

Жизненный цикл ключа доступа

Постраничная навигация

Ошибки

Совместимость и прекращение поддержки

Общедоступный API, MCP и веб-приложение

Получение помощи

См. также