Краткое руководство по API

Создайте сервисную учётную запись и ключ API в Developer Hub, а затем отправьте первый запрос. В этом кратком руководстве используется аутентификация по ключу API; клиент OAuth не требуется. Если для вашей интеграции необходимы краткосрочные токены доступа OAuth, см. раздел Аутентификация.

Предварительные требования

Доступ администратора к Панели управления Living Security.
Раздел Developer Hub, отображаемый в меню Настройки → Интеграции и разработчики → Developer Hub.

Создание учётных данных

Создайте сервисную учётную запись

В Developer Hub откройте вкладку Сервисные учётные записи и создайте учётную запись. Укажите понятное имя (например, reporting-pipeline) и предоставьте разрешения, которые могут использовать её ключи. Для этого руководства достаточно organization:read.Разрешения учётной записи являются верхним пределом для каждого ключа, созданного в ней: ключ никогда не сможет выполнять больше действий, чем допускает его сервисная учётная запись.

Создайте ключ API

Откройте страницу сведений о сервисной учётной записи и создайте ключ. Выберите разрешения, необходимые именно этому ключу (подмножество разрешений учётной записи), и срок действия — 30, 90 или 365 дней либо произвольный период. Срок действия обязателен.Секрет ключа начинается с lsk_live_ и отображается только один раз. Сразу скопируйте его в менеджер секретов; позднее получить его будет невозможно.

Никогда не фиксируйте секреты ключей API в системе управления версиями и не встраивайте их в клиентский код. Любой, кто обладает секретом, может действовать с разрешениями этого ключа.

Выберите регион

Обращайтесь к региональному хосту /v1, который соответствует расположению данных организации. Ключи проходят аутентификацию только на этом хосте.

Регион	Базовый URL
US	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

Если вы не уверены, какой хост использовать, см. раздел Регионы. Действительный ключ, отправленный в другой регион, завершается ошибкой unauthorized. Чтобы переключить хост, используйте раскрывающийся список регионов в примере ниже.

Отправьте первый запрос

Загрузите LIVING_SECURITY_API_KEY из менеджера секретов в переменные окружения процесса, отправляющего запрос. Приведённые ниже примеры считывают его, не встраивая секрет в исходный код. Для Python сначала установите requests.Обратитесь к API, указав секрет в поле пароля или имени пользователя HTTP Basic auth — подходят оба варианта, поэтому клиенты, требующие заполнения обоих полей (например, веб-коннектор Power BI), могут указать в другом поле заполнитель, такой как apikey.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

В случае успеха в ответе будет возвращена ваша организация:

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

Если вы получили такой ответ, ваши учётные данные работают. Запрос также появится во вкладке Журналы запросов Developer Hub в течение нескольких мгновений.

Аутентификация Bearer с тем же секретом (Authorization: Bearer lsk_live_...) также работает. Basic auth предусмотрена для инструментов, поддерживающих только имя пользователя и пароль, например веб-коннектора Power BI.

Как работает аутентификация

Учётные данные определяют организацию. Запросы /v1 не содержат селектора клиента: ни сегмента пути с организацией, ни заголовка организации. Отправка заголовка x-organization-id отклоняется с ошибкой invalid_request. Хост по-прежнему должен соответствовать региону этой организации. См. Регионы.
Разрешения проверяются для каждой операции. Для каждой операции /v1 требуется именованное разрешение (например, для GET /v1/organization требуется organization:read). Если у ключа нет нужного разрешения, он получает 403 с кодом insufficient_permission.
Срок действия ключей ограничен, их можно ротировать без простоя. О ротации с перекрывающимся периодом см. в разделе Ключи API.

Чтение ответов с ошибками

Каждая ошибка /v1 представлена в формате application/problem+json (RFC 9457) со стабильным машинным кодом. Например, запрос с отсутствующими или неизвестными учётными данными возвращает:

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

Ориентируйтесь на code, а не на detail. Для получения шагов по устранению следуйте doc_url, а при обращении в службу поддержки указывайте request_id — он совпадает с заголовком ответа Request-Id и записями в журналах запросов Developer Hub. Полный перечень кодов приведён в справочнике по ошибкам.

Версии контракта

Каждый ответ возвращает версию контракта, которая его обработала, в заголовке Living-Security-Version вместе с заголовком Request-Id для корреляции. Запрос можно привязать к опубликованной версии контракта по дате:

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

Версия определяется в следующем порядке: заголовок запроса, если он присутствует; в противном случае версия по умолчанию, закреплённая за сервисной учётной записью; в противном случае последняя опубликованная версия. Запрос версии, которая не опубликована (или срок поддержки которой истёк), возвращает 400 с кодом unsupported_version. Опубликованные версии и их изменения перечислены в журнале изменений API.

Устранение неполадок при первом запросе

Результат	Дальнейшие действия
`401 unauthorized`	Проверьте секрет, срок его действия и регион организации. Не пробуйте другие хосты с действующими учётными данными.
`403 insufficient_permission`	Предоставьте `organization:read` как сервисной учётной записи, так и её ключу.
`400 unsupported_version`	Выберите опубликованную версию в журнале изменений.
`429 rate_limited`	Дождитесь `Retry-After`; следуйте примеру ограниченного числа повторных попыток.
Тайм-аут сети	Проверьте подключение и повторите этот запрос на чтение в пределах лимита повторных попыток вашего приложения.

При других ошибках следуйте указаниям doc_url в ответе. Сохраните Request-Id для службы поддержки; никогда не указывайте заголовок Authorization или ваш ключ API в обращении.

Дальнейшие шаги

Регионы

Выберите хост /v1 для US или EU, соответствующий организации.

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

Просматривайте списки с помощью page_token и оболочки списка.

Ограничения частоты запросов

Узнайте о лимитах запросов и обработке ответов 429.

Справочник по ошибкам

Все коды ошибок, их HTTP-статусы и способы устранения.

Developer Hub

Управляйте сервисными учётными записями, ключами API и журналами запросов.

Центр разработчика

Публичный API v1

Справочник по API v1

Краткое руководство по API

Предварительные требования

Создание учётных данных

Как работает аутентификация

Чтение ответов с ошибками

Версии контракта

Устранение неполадок при первом запросе

Дальнейшие шаги

Регионы

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

Ограничения частоты запросов

Справочник по ошибкам

Developer Hub

Центр разработчика

Публичный API v1

Справочник по API v1

​Предварительные требования

​Создание учётных данных

​Как работает аутентификация

​Чтение ответов с ошибками

​Версии контракта

​Устранение неполадок при первом запросе

​Дальнейшие шаги

Регионы

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

Ограничения частоты запросов

Справочник по ошибкам

Developer Hub

Предварительные требования

Создание учётных данных

Как работает аутентификация

Чтение ответов с ошибками

Версии контракта

Устранение неполадок при первом запросе

Дальнейшие шаги