> ## 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 в Developer Hub, выполните аутентификацию с помощью Basic auth и отправьте первый запрос к Public API Living Security. Создайте сервисную учётную запись и ключ API в Developer Hub, а затем отправьте первый запрос. В этом кратком руководстве используется аутентификация по ключу API; клиент OAuth не требуется. Если для вашей интеграции необходимы краткосрочные токены доступа OAuth, см. раздел [Аутентификация](/ru/developers/v1/authentication). ## Предварительные требования * Доступ администратора к Панели управления Living Security. * Раздел Developer Hub, отображаемый в меню **Настройки → Интеграции и разработчики → Developer Hub**. ## Создание учётных данных В Developer Hub откройте вкладку **Сервисные учётные записи** и создайте учётную запись. Укажите понятное имя (например, `reporting-pipeline`) и предоставьте разрешения, которые могут использовать её ключи. Для этого руководства достаточно `organization:read`. Разрешения учётной записи являются верхним пределом для каждого ключа, созданного в ней: ключ никогда не сможет выполнять больше действий, чем допускает его сервисная учётная запись. Откройте страницу сведений о сервисной учётной записи и создайте ключ. Выберите разрешения, необходимые именно этому ключу (подмножество разрешений учётной записи), и срок действия — 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` | Если вы не уверены, какой хост использовать, см. раздел [Регионы](/ru/developers/v1/regions). Действительный ключ, отправленный в другой регион, завершается ошибкой `unauthorized`. Чтобы переключить хост, используйте раскрывающийся список регионов в примере ниже. Загрузите `LIVING_SECURITY_API_KEY` из менеджера секретов в переменные окружения процесса, отправляющего запрос. Приведённые ниже примеры считывают его, не встраивая секрет в исходный код. Для Python сначала установите `requests`. Обратитесь к API, указав секрет в поле пароля или имени пользователя HTTP Basic auth — подходят оба варианта, поэтому клиенты, требующие заполнения обоих полей (например, веб-коннектор Power BI), могут указать в другом поле заполнитель, такой как `apikey`. ```bash cURL theme={null} 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" ``` ```bash cURL (key as username) theme={null} 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" ``` ```python Python theme={null} 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()) ``` В случае успеха в ответе будет возвращена ваша организация: ```json Response theme={null} { "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`. Хост по-прежнему должен соответствовать региону этой организации. См. [Регионы](/ru/developers/v1/regions). * **Разрешения проверяются для каждой операции.** Для каждой операции `/v1` требуется именованное разрешение (например, для `GET /v1/organization` требуется `organization:read`). Если у ключа нет нужного разрешения, он получает `403` с кодом `insufficient_permission`. * **Срок действия ключей ограничен, их можно ротировать без простоя.** О ротации с перекрывающимся периодом см. в разделе [Ключи API](/ru/developers/developer-hub/api-keys). ## Чтение ответов с ошибками Каждая ошибка `/v1` представлена в формате `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) со стабильным машинным кодом. Например, запрос с отсутствующими или неизвестными учётными данными возвращает: ```json 401 Unauthorized theme={null} { "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. Полный перечень кодов приведён в [справочнике по ошибкам](/ru/developers/v1/errors/overview). ## Версии контракта Каждый ответ возвращает версию контракта, которая его обработала, в заголовке `Living-Security-Version` вместе с заголовком `Request-Id` для корреляции. Запрос можно привязать к опубликованной версии контракта по дате: ```bash cURL theme={null} 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](/ru/developers/v1/changelog). ## Устранение неполадок при первом запросе | Результат | Дальнейшие действия | | - | - | | `401 unauthorized` | Проверьте секрет, срок его действия и регион организации. Не пробуйте другие хосты с действующими учётными данными. | | `403 insufficient_permission` | Предоставьте `organization:read` как сервисной учётной записи, так и её ключу. | | `400 unsupported_version` | Выберите опубликованную версию в [журнале изменений](/ru/developers/v1/changelog). | | `429 rate_limited` | Дождитесь `Retry-After`; следуйте [примеру ограниченного числа повторных попыток](/ru/developers/v1/rate-limits). | | Тайм-аут сети | Проверьте подключение и повторите этот запрос на чтение в пределах лимита повторных попыток вашего приложения. | При других ошибках следуйте указаниям `doc_url` в ответе. Сохраните `Request-Id` для службы поддержки; никогда не указывайте заголовок Authorization или ваш ключ API в обращении. ## Дальнейшие шаги Выберите хост `/v1` для US или EU, соответствующий организации. Просматривайте списки с помощью `page_token` и оболочки списка. Узнайте о лимитах запросов и обработке ответов `429`. Все коды ошибок, их HTTP-статусы и способы устранения. Управляйте сервисными учётными записями, ключами API и журналами запросов. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.