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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```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"
```

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

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

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

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

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

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

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

Зафиксируйте версию SDK в пределах совместимой основной версии и перед обновлением изучите примечания к выпуску. Источником истины о схеме считайте сформированный справочник Public API Reference, а не собственные клиентские приложения производителя.

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

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

О подключении ИИ-инструмента к Living Security см. в разделе [Интеграция MCP](/ru/integrations/mcp).

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

Обратитесь в [службу поддержки Living Security](mailto:support@livingsecurity.com) и укажите:

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

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

## См. также

<CardGroup cols={2}>
  <Card title="Ключи доступа к API" icon="key" href="/ru/integrations/api-keys">
    Создание, ротация и отзыв учётных данных API.
  </Card>

  <Card title="Интеграция MCP" icon="robot" href="/ru/integrations/mcp">
    Подключение поддерживаемых ИИ-инструментов через Model Context Protocol.
  </Card>
</CardGroup>


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