Rychlý start s API

Vytvořte v Developer Hub servisní účet a klíč API a poté odešlete svůj první požadavek. Tento rychlý start používá autentizaci pomocí klíče API; klient OAuth nepotřebujete. Pokud vaše integrace vyžaduje krátkodobé přístupové tokeny OAuth, přečtěte si část Autentizace.

Předpoklady

Přístup správce k Nástěnce Living Security.
Zobrazený Developer Hub v nabídce Nastavení → Integrace a vývojáři → Developer Hub.

Vytvoření přihlašovacích údajů

Vytvořte servisní účet

V Developer Hub otevřete kartu Servisní účty a vytvořte účet. Dejte mu popisný název (například reporting-pipeline) a udělte oprávnění, která mohou jeho klíče používat – pro tento návod stačí organization:read.Oprávnění účtu představují horní hranici pro každý klíč vytvořený v rámci něj: klíč nikdy nemůže dělat více, než jeho servisní účet povoluje.

Vytvořte klíč API

Otevřete stránku s podrobnostmi o servisním účtu a vytvořte klíč. Vyberte oprávnění, která tento konkrétní klíč potřebuje (podmnožinu oprávnění účtu), a dobu platnosti – 30, 90 nebo 365 dní, případně vlastní období. Platnost je povinná.Tajný klíč začíná lsk_live_ a zobrazí se pouze jednou. Ihned ho zkopírujte do správce tajných klíčů; později jej nelze znovu zobrazit.

Tajné klíče API nikdy neukládejte do správy verzí ani je nevkládejte do kódu na straně klienta. Kdokoli, kdo tajný klíč má, může jednat s oprávněními tohoto klíče.

Zvolte region

Volejte regionální hostitele /v1, který odpovídá umístění dat organizace. Klíče se ověřují pouze na tomto hostiteli.

Region	Základní URL
USA	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

Pokud si nejste jisti, kterého hostitele použít, přečtěte si část Regiony. Platný klíč odeslaný do druhého regionu selže s chybou unauthorized. Hostitele přepnete pomocí rozevíracího seznamu regionů u ukázky níže.

Odešlete první požadavek

Načtěte LIVING_SECURITY_API_KEY ze správce tajných klíčů do prostředí procesu, který požadavek odesílá. Níže uvedené příklady jej čtou bez vložení tajného klíče do zdrojového kódu. Pro Python nejprve nainstalujte requests.Zavolejte API s tajným klíčem v poli hesla nebo uživatelského jména pro HTTP Basic autentizaci – funguje obojí, takže klienti, které vyžadují vyplnění obou polí (například konektor Web v Power BI), mohou do druhého pole zadat zástupnou hodnotu, například 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())

Úspěšná odpověď vrátí vaši organizaci:

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

Pokud obdržíte tuto odpověď, vaše přihlašovací údaje fungují. Požadavek se také během okamžiku zobrazí na kartě Protokoly požadavků v Developer Hub.

Funguje také autentizace Bearer se stejným tajným klíčem (Authorization: Bearer lsk_live_...). Autentizace Basic existuje proto, aby se mohly připojit nástroje, které podporují pouze uživatelské jméno a heslo – například konektor Web v Power BI.

Jak autentizace funguje

Přihlašovací údaje určují organizaci. Požadavky /v1 neobsahují žádný selektor tenanta: ani segment cesty s organizací, ani hlavičku organizace. Odeslání hlavičky x-organization-id je odmítnuto s chybou invalid_request. Hostitel musí stále odpovídat regionu dané organizace. Viz Regiony.
Oprávnění se kontrolují pro každou operaci. Každá operace /v1 vyžaduje pojmenované oprávnění (například GET /v1/organization vyžaduje organization:read). Klíč, kterému oprávnění chybí, obdrží 403 s kódem insufficient_permission.
Klíče mají omezenou platnost a lze je rotovat bez výpadku. Rotaci s překryvným oknem najdete v části Klíče API.

Čtení chybových odpovědí

Každá chyba /v1 má formát application/problem+json (RFC 9457) se stabilním strojovým kódem. Například požadavek s chybějícími nebo neznámými přihlašovacími údaji vrátí:

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
}

Větvete podle code, nikdy podle detail. Postupujte podle doc_url, kde najdete kroky k řešení, a při kontaktování podpory uveďte request_id – odpovídá hlavičce odpovědi Request-Id a protokolům požadavků v Developer Hub. Úplný seznam kódů je v referenci chyb.

Verze kontraktu

Každá odpověď v hlavičce Living-Security-Version vrací verzi kontraktu, která ji obsloužila, spolu s hlavičkou Request-Id pro korelaci. Požadavek můžete připnout ke zveřejněné verzi kontraktu podle data:

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"

Verze se určuje v tomto pořadí: hlavička požadavku, pokud je přítomna, jinak výchozí verze připnutá u servisního účtu, jinak nejnovější zveřejněná verze. Vyžádání verze, která není zveřejněna (nebo je po datu ukončení podpory), vrátí 400 s kódem unsupported_version. Zveřejněné verze a jejich změny jsou uvedeny v seznamu změn API.

Řešení potíží s prvním požadavkem

Výsledek	Další postup
`401 unauthorized`	Zkontrolujte tajný klíč, jeho platnost a region organizace. Nezkoušejte jiné hostitele s platnými přihlašovacími údaji.
`403 insufficient_permission`	Udělte `organization:read` servisnímu účtu i jeho klíči.
`400 unsupported_version`	Vyberte zveřejněnou verzi ze seznamu změn.
`429 rate_limited`	Počkejte na `Retry-After`; postupujte podle příkladu omezeného opakování.
Vypršení časového limitu sítě	Zkontrolujte konektivitu a zopakujte toto čtení v rámci rozpočtu opakování vaší aplikace.

U ostatních chyb postupujte podle doc_url v odpovědi. Uschovejte Request-Id pro podporu; do tiketu nikdy nevkládejte hlavičku Authorization ani svůj klíč API.

Další kroky

Regiony

Zvolte hostitele /v1 pro USA nebo EU pro danou organizaci.

Stránkování

Procházejte seznamy pomocí page_token a obálky seznamu.

Limity požadavků

Seznamte se s rozpočty požadavků a zpracováním odpovědí 429.

Reference chyb

Všechny chybové kódy, jejich stavy HTTP a způsob řešení.

Developer Hub

Správa servisních účtů, klíčů API a protokolů požadavků.

Centrum pro vývojáře

Veřejné API v1

Reference API v1

Předpoklady

Vytvoření přihlašovacích údajů

Jak autentizace funguje

Čtení chybových odpovědí

Verze kontraktu

Řešení potíží s prvním požadavkem

Další kroky

Regiony

Stránkování

Limity požadavků

Reference chyb

Developer Hub

Centrum pro vývojáře

Veřejné API v1

Reference API v1

​Předpoklady

​Vytvoření přihlašovacích údajů

​Jak autentizace funguje

​Čtení chybových odpovědí

​Verze kontraktu

​Řešení potíží s prvním požadavkem

​Další kroky

Regiony

Stránkování

Limity požadavků

Reference chyb

Developer Hub

Předpoklady

Vytvoření přihlašovacích údajů

Jak autentizace funguje

Čtení chybových odpovědí

Verze kontraktu

Řešení potíží s prvním požadavkem

Další kroky