Швидкий старт з API

Створіть службовий обліковий запис і API-ключ у Developer Hub, а потім надішліть свій перший запит. У цьому короткому посібнику використовується автентифікація за API-ключем; клієнт OAuth вам не потрібен. Якщо вашій інтеграції потрібні короткострокові токени доступу OAuth, див. розділ Автентифікація.

Передумови

Доступ адміністратора до Dashboard Living Security.
Developer Hub, доступний за шляхом Settings → Integrations & Developers → Developer Hub.

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

Створіть службовий обліковий запис

У Developer Hub відкрийте вкладку Service accounts і створіть обліковий запис. Вкажіть описову назву (наприклад, 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"
}

Якщо ви отримали таку відповідь, ваші облікові дані працюють. Цей запит також з’явиться на вкладці Request logs у 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

Передумови

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

Як працює автентифікація

Читання відповідей із помилками

Версії контракту

Усунення несправностей першого запиту

Наступні кроки

Регіони

Пагінація

Ліміти запитів

Довідник з помилок

Developer Hub

Центр розробників

Публічний API v1

Довідник з API v1

​Передумови

​Створення облікових даних

​Як працює автентифікація

​Читання відповідей із помилками

​Версії контракту

​Усунення несправностей першого запиту

​Наступні кроки

Регіони

Пагінація

Ліміти запитів

Довідник з помилок

Developer Hub

Передумови

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

Як працює автентифікація

Читання відповідей із помилками

Версії контракту

Усунення несправностей першого запиту

Наступні кроки