Szybki start z API

Utwórz konto usługi i klucz API w Developer Hub, a następnie wyślij pierwsze żądanie. W tym przewodniku szybkiego startu używane jest uwierzytelnianie kluczem API; klient OAuth nie jest potrzebny. Jeśli Twoja integracja wymaga krótkotrwałych tokenów dostępu OAuth, zobacz Uwierzytelnianie.

Wymagania wstępne

Dostęp administratora do Pulpitu Living Security.
Widoczny Developer Hub w sekcji Ustawienia → Integracje & Developers → Developer Hub.

Tworzenie poświadczeń

Utwórz konto usługi

W Developer Hub otwórz kartę Service accounts i utwórz konto. Nadaj mu opisową nazwę (na przykład reporting-pipeline) i przyznaj uprawnienia, z których mogą korzystać jego klucze — w tym przewodniku wystarczy organization:read.Uprawnienia konta stanowią górną granicę dla każdego klucza utworzonego w jego ramach: klucz nigdy nie może robić więcej, niż pozwala jego konto usługi.

Utwórz klucz API

Otwórz stronę szczegółów konta usługi i utwórz klucz. Wybierz uprawnienia potrzebne dla tego konkretnego klucza (podzbiór uprawnień konta) oraz okres ważności — 30, 90 lub 365 dni albo okres niestandardowy. Okres ważności jest obowiązkowy.Tajny klucz zaczyna się od lsk_live_ i jest wyświetlany tylko raz. Natychmiast skopiuj go do menedżera sekretów; nie będzie można go później odzyskać.

Nigdy nie umieszczaj tajnych kluczy API w systemie kontroli wersji ani w kodzie po stronie klienta. Każdy, kto posiada taki sekret, może działać z uprawnieniami tego klucza.

Wybierz region

Wywołuj regionalny host /v1 odpowiadający lokalizacji danych organizacji. Klucze uwierzytelniają się wyłącznie na tym hoście.

Region	Bazowy adres URL
US	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

Jeśli nie masz pewności, którego hosta użyć, zobacz Regiony. Prawidłowy klucz wysłany do drugiego regionu kończy się błędem unauthorized. Aby zmienić host, użyj listy rozwijanej regionu w poniższym przykładzie.

Wyślij pierwsze żądanie

Załaduj LIVING_SECURITY_API_KEY z menedżera sekretów do środowiska procesu wysyłającego żądanie. Poniższe przykłady odczytują go bez umieszczania sekretu w kodzie źródłowym. W przypadku Pythona najpierw zainstaluj requests.Wywołaj API, podając sekret w polu hasła lub nazwy użytkownika w uwierzytelnianiu HTTP Basic — obie opcje działają, więc klienci wymagający wypełnienia obu pól (np. łącznik Web w Power BI) mogą wpisać w drugim polu symbol zastępczy, taki jak 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())

Pomyślna odpowiedź zwraca Twoją organizację:

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

Jeśli otrzymasz taką odpowiedź, Twoje poświadczenia działają. Żądanie pojawi się też po chwili na karcie Request logs w Developer Hub.

Działa również uwierzytelnianie Bearer z tym samym sekretem (Authorization: Bearer lsk_live_...). Uwierzytelnianie Basic istnieje po to, aby narzędzia obsługujące wyłącznie nazwę użytkownika i hasło — takie jak łącznik Web w Power BI — mogły się połączyć.

Jak działa uwierzytelnianie

Poświadczenia określają organizację. Żądania /v1 nie zawierają selektora tenanta: ani segmentu ścieżki z organizacją, ani nagłówka organizacji. Wysłanie nagłówka x-organization-id kończy się odrzuceniem z kodem invalid_request. Host nadal musi odpowiadać regionowi tej organizacji. Zobacz Regiony.
Uprawnienia są sprawdzane dla każdej operacji. Każda operacja /v1 wymaga nazwanego uprawnienia (na przykład GET /v1/organization wymaga organization:read). Klucz bez wymaganego uprawnienia otrzymuje 403 z kodem insufficient_permission.
Klucze wygasają i można je rotować bez przestojów. Informacje o rotacji z okresem nakładania się znajdziesz w sekcji Klucze API.

Odczytywanie odpowiedzi z błędami

Każdy błąd /v1 jest w formacie application/problem+json (RFC 9457) i zawiera stały kod maszynowy. Na przykład żądanie z brakującymi lub nieznanymi poświadczeniami zwraca:

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
}

Rozgałęziaj logikę na podstawie code, nigdy detail. Kroki rozwiązania problemu znajdziesz w doc_url. Kontaktując się z pomocą techniczną, podaj request_id — odpowiada on nagłówkowi odpowiedzi Request-Id oraz logom żądań w Developer Hub. Pełny zestaw kodów znajduje się w opisie błędów.

Wersje kontraktu

Każda odpowiedź zwraca w nagłówku Living-Security-Version wersję kontraktu, która ją obsłużyła, oraz nagłówek Request-Id służący do korelacji. Żądanie można przypiąć do opublikowanej wersji kontraktu według daty:

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"

Wersja jest ustalana w następującej kolejności: nagłówek żądania, jeśli występuje; w przeciwnym razie domyślna wersja przypięta do konta usługi; w przeciwnym razie najnowsza opublikowana wersja. Żądanie wersji, która nie jest opublikowana (lub minęła jej data wycofania), zwraca 400 z kodem unsupported_version. Opublikowane wersje i ich zmiany są wymienione w dzienniku zmian API.

Rozwiązywanie problemów z pierwszym żądaniem

Wynik	Następne działanie
`401 unauthorized`	Sprawdź sekret, jego okres ważności i region organizacji. Nie próbuj używać innych hostów z aktywnymi poświadczeniami.
`403 insufficient_permission`	Przyznaj `organization:read` zarówno kontu usługi, jak i jego kluczowi.
`400 unsupported_version`	Wybierz opublikowaną wersję z dziennika zmian.
`429 rate_limited`	Poczekaj na `Retry-After`; skorzystaj z przykładu ograniczonych ponowień.
Przekroczenie limitu czasu sieci	Sprawdź łączność i ponów ten odczyt w ramach budżetu ponowień swojej aplikacji.

W przypadku innych błędów postępuj zgodnie z doc_url podanym w odpowiedzi. Zachowaj Request-Id na potrzeby pomocy technicznej; nigdy nie umieszczaj w zgłoszeniu nagłówka Authorization ani klucza API.

Następne kroki

Regiony

Wybierz dla organizacji host /v1 w regionie US lub EU.

Paginacja

Przeglądaj listy za pomocą page_token i koperty listy.

Limity żądań

Poznaj budżety żądań i obsługuj odpowiedzi 429.

Opis błędów

Każdy kod błędu, jego status HTTP i sposób rozwiązania.

Developer Hub

Zarządzaj kontami usług, kluczami API i logami żądań.

Centrum deweloperskie

Publiczne API v1

Dokumentacja referencyjna API v1

Wymagania wstępne

Tworzenie poświadczeń

Jak działa uwierzytelnianie

Odczytywanie odpowiedzi z błędami

Wersje kontraktu

Rozwiązywanie problemów z pierwszym żądaniem

Następne kroki

Regiony

Paginacja

Limity żądań

Opis błędów

Developer Hub

Centrum deweloperskie

Publiczne API v1

Dokumentacja referencyjna API v1

​Wymagania wstępne

​Tworzenie poświadczeń

​Jak działa uwierzytelnianie

​Odczytywanie odpowiedzi z błędami

​Wersje kontraktu

​Rozwiązywanie problemów z pierwszym żądaniem

​Następne kroki

Regiony

Paginacja

Limity żądań

Opis błędów

Developer Hub

Wymagania wstępne

Tworzenie poświadczeń

Jak działa uwierzytelnianie

Odczytywanie odpowiedzi z błędami

Wersje kontraktu

Rozwiązywanie problemów z pierwszym żądaniem

Następne kroki