> ## 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 та надішліть свій перший запит до Living Security Public API.
Створіть службовий обліковий запис і API-ключ у Developer Hub, а потім надішліть
свій перший запит. У цьому короткому посібнику використовується автентифікація за API-ключем; клієнт OAuth вам не потрібен. Якщо вашій
інтеграції потрібні короткострокові токени доступу OAuth, див. розділ [Автентифікація](/uk/developers/v1/authentication).
## Передумови
* Доступ адміністратора до Dashboard Living Security.
* Developer Hub, доступний за шляхом **Settings → Integrations & Developers →
Developer Hub**.
## Створення облікових даних
У Developer Hub відкрийте вкладку **Service accounts** і створіть
обліковий запис. Вкажіть описову назву (наприклад, `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` |
Якщо ви не впевнені, який хост використовувати, див. розділ [Регіони](/uk/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"
}
```
Якщо ви отримали таку відповідь, ваші облікові дані працюють. Цей запит також з’явиться на
вкладці **Request logs** у Developer Hub за лічені митті.
Автентифікація Bearer з тим самим секретом (`Authorization: Bearer
lsk_live_...`) також працює. Basic auth існує для того, щоб інструменти, які підтримують лише
ім’я користувача та пароль, як-от веб-конектор Power BI, могли підключатися.
## Як працює автентифікація
* **Облікові дані визначають організацію.** Запити `/v1` не містять
селектора тенанта: ні сегмента шляху з організацією, ні заголовка організації.
Надсилання заголовка `x-organization-id` відхиляється з помилкою `invalid_request`.
Хост усе одно має відповідати регіону цієї організації. Див.
[Регіони](/uk/developers/v1/regions).
* **Дозволи перевіряються для кожної операції.** Кожна операція `/v1` потребує
певного дозволу (наприклад, `GET /v1/organization` потребує
`organization:read`). Ключ без потрібного дозволу отримує `403` з кодом
`insufficient_permission`.
* **Ключі мають термін дії й можуть ротуватися без простою.** Про ротацію з періодом перекриття див. розділ
[API-ключі](/uk/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. Повний
перелік кодів наведено в [довіднику з помилок](/uk/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](/uk/developers/v1/changelog).
## Усунення несправностей першого запиту
| Результат | Наступна дія |
| - | - |
| `401 unauthorized` | Перевірте секрет, термін його дії та регіон організації. Не пробуйте інші хости з робочими обліковими даними. |
| `403 insufficient_permission` | Надайте `organization:read` і службовому обліковому запису, і його ключу. |
| `400 unsupported_version` | Виберіть опубліковану версію з [журналу змін](/uk/developers/v1/changelog). |
| `429 rate_limited` | Зачекайте `Retry-After`; скористайтеся [прикладом обмежених повторних спроб](/uk/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.