Starší veřejné API

Tato příručka se týká stávajících integrací /api/v1, které vyměňují přístupový klíč API za bearer token. Jejich přihlašovací údaje a formát požadavků se liší od veřejného API /v1. Pro novou integraci začněte v rychlém startu API a v části Ověřování. Nové API /v1 používá klíče API servisních účtů nebo přístupové tokeny OAuth.

Než začnete

Potřebujete:

přístup do Living Security, který umožňuje správu přístupových klíčů API
přístupový klíč API vytvořený v části Nastavení → Access Keys
jednorázové tajemství přístupového klíče zobrazené při vytvoření přihlašovacích údajů
ID vydavatele API (API issuer ID), které vám společnost Living Security poskytla spolu s přihlašovacími údaji k veřejnému API
regionální základní URL pro organizaci, kterou integrujete
serverové běhové prostředí a správce tajemství

Tajemství přístupových klíčů nesmí být umístěna v kódu prohlížeče, v mobilních aplikacích, ve správě zdrojového kódu, v proměnných prostředí na straně klienta, v tiketech ani ve sdílených protokolech.

Dialog Access Keys zobrazuje jednorázové tajemství, ale nezobrazuje ID vydavatele API. Pokud vám společnost Living Security neposkytla ID vydavatele spolu s přihlašovacími údaji k veřejnému API, vyžádejte si je od podpory Living Security. ID vydavatele není totéž co ID přístupového klíče ani ID organizace.

Regionální hostitelé

Starší kontrakt používá tyto regionální produkční hostitele /api/v1:

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

Použijte region přiřazený organizaci v Living Security. Neměňte region jako způsob obcházení chyby autorizace nebo dostupnosti.

Starší zdroje

Zdroj	Podporované operace
Lidé	Vyhledávání osob v organizaci a načtení členství osoby
Přístupové klíče API	Vytvoření, výpis, rotace a odvolání přístupových klíčů API

Úplný seznam operací, parametrů, požadavků, odpovědí a schémat najdete v části Developers → Public API Reference. Pokud operace v referenci není, není v současnosti součástí veřejného API.

Ověřování

Přístup k veřejnému API má dvě fáze:

Vyměňte tajný přístupový klíč a ID vydavatele API za krátkodobý bearer token a ID organizace.
Odesílejte bearer token a ID organizace s každým požadavkem API.

Požadované hlavičky požadavku jsou:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

Hlavička organizace musí obsahovat organizaci vrácenou při výměně přístupového klíče. Klíč neopravňuje k přístupu k libovolnému ID organizace.

SDK pro TypeScript

Nainstalujte aktuální hlavní verzi:

npm install @livingsecurity/sdk@^1

Poté vyměňte klíč a nakonfigurujte SDK:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

Pro organizaci v EU použijte základní URL pro EU. Výměna pomocí SDK je určena pro serverová běhová prostředí Node.js.

Přímý požadavek REST

Pokud výměnu provádíte mimo SDK, odesílejte bearer token a ID organizace s každým požadavkem:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

Bearer tokeny jsou krátkodobé. Pro získání nového tokenu vyměňte přístupový klíč znovu, místo abyste bearer token uchovávali jako trvalé přihlašovací údaje.

Životní cyklus přístupového klíče

Klíče pojmenujte podle integrace nebo automatizace, která je vlastní.
Zvolte nejméně privilegované rozsahy (scopes) nabízené ve formuláři přístupového klíče.
Jednorázové tajemství okamžitě uložte; po vytvoření nebo rotaci jej nelze znovu zobrazit.
Klíč rotujte v části Nastavení → Access Keys a nahrazující klíč nasaďte před odvoláním původních přihlašovacích údajů.
Odvolejte klíče, které se již nepoužívají nebo jejichž tajemství mohlo být odhaleno.
Pro integrace bez lidského uživatele používejte klíče servisních účtů, pokud je tento typ klíče pro vaši organizaci dostupný.

Stránkování

Vyhledávání osob podporuje parametry limit, cursor, offset a includeTotal. Pro sekvenční procházení preferujte kurzor vrácený předchozí odpovědí.

limit má výchozí hodnotu 50 a přijímá hodnoty 1–100.
cursor pokračuje od předchozí odpovědi.
offset přeskočí zadaný počet záznamů a výchozí hodnota je 0.
includeTotal=true vyžádá přesný počet po filtrování; pokud počet nepotřebujete, parametr vynechte.

Čtěte objekt pagination vrácený koncovým bodem. Nevypočítávejte další stránku z počtu přijatých řádků a nekombinujte nezávisle stránkované požadavky s vlastním řazením dílčích výsledků.

Chyby

Zdokumentované chyby ve formátu JSON mají tento obecný tvar:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message může být řetězec nebo pole zpráv o validaci.

Stav	Význam	Postup
`400`	Neplatné parametry nebo tělo požadavku	Opravte uvedené chyby validace
`401`	Bearer token chybí, je neplatný nebo vypršel	Vyměňte přístupový klíč znovu a zkuste to jednou znovu
`403`	Přihlašovací údaje nemají oprávnění nebo přístup k organizaci	Zkontrolujte rozsahy klíče a kontext organizace
`404`	Zdroj v autorizované organizaci neexistuje	Ověřte ID zdroje a organizaci
`408`	Časový limit požadavku vypršel	Opakujte s omezeným exponenciálním prodlužováním prodlev
`429`	Dosažen limit počtu požadavků	Počkejte alespoň tak dlouho, jak uvádí `Retry-After`, pokud je přítomno
`5xx`	Dočasné selhání služby	Bezpečné operace čtení opakujte s omezeným exponenciálním prodlužováním prodlev

Kurátorský kontrakt v současnosti nezveřejňuje jeden univerzální číselný limit počtu požadavků ani nezaručuje hlavičku odpovědi s ID požadavku pro každou operaci. Při žádosti o podporu uveďte čas v UTC, metodu, cestu, stav a očištěné tělo odpovědi. Operace vytvoření, rotace, odvolání nebo odstranění automaticky neopakujte, pokud operace výslovně nedokumentuje idempotenci. Po nejednoznačném selhání sítě zkontrolujte aktuální stav zdroje.

Kompatibilita a vyřazování

V1 se standardně vyvíjí aditivně. Klienti musí ignorovat neznámá pole odpovědi. Zásadní změna vyžaduje zdokumentovanou cestu migrace; vyřazované operace zůstávají v referenci s uvedením důvodu, náhrady (je-li dostupná) a data ukončení podpory po dobu migračního období. Zafixujte SDK na kompatibilní hlavní verzi a před aktualizací si přečtěte poznámky k vydání. Za zdroj pravdy o schématu považujte vygenerovanou Public API Reference, nikoli klienty aplikací první strany.

Veřejné API, MCP a webová aplikace

Rozhraní	Určeno pro	Model kompatibility
Veřejné API	Zákaznické systémy, partnery a externí automatizaci	Stabilní, verzované zdroje
MCP	Interakce nástrojů AI řízené oprávněními	Kontrakty nástrojů a kompaktní strukturované výstupy
Webová aplikace	Pracovní postupy lidí v produktu Living Security	Kontrakty vlastněné aplikací, které se mohou vyvíjet spolu s UI

Informace o připojení nástroje AI k Living Security najdete v části Integrace MCP.

Získání pomoci

Kontaktujte podporu Living Security a uveďte:

organizaci a region
název a verzi SDK, pokud se používá
časové razítko v UTC, metodu a cestu
stav HTTP a očištěné tělo chyby

Nikdy neuvádějte tajemství přístupových klíčů, bearer tokeny ani soukromá data zákazníků.

Veřejné API

Reference veřejného API

Než začnete

Regionální hostitelé

Starší zdroje

Ověřování

SDK pro TypeScript

Přímý požadavek REST

Životní cyklus přístupového klíče

Stránkování

Chyby

Kompatibilita a vyřazování

Veřejné API, MCP a webová aplikace

Získání pomoci

Související

Přístupové klíče API

Integrace MCP

Veřejné API

Reference veřejného API

​Než začnete

​Regionální hostitelé

​Starší zdroje

​Ověřování

​SDK pro TypeScript

​Přímý požadavek REST

​Životní cyklus přístupového klíče

​Stránkování

​Chyby

​Kompatibilita a vyřazování

​Veřejné API, MCP a webová aplikace

​Získání pomoci

​Související

Přístupové klíče API

Integrace MCP

Než začnete

Regionální hostitelé

Starší zdroje

Ověřování

SDK pro TypeScript

Přímý požadavek REST

Životní cyklus přístupového klíče

Stránkování

Chyby

Kompatibilita a vyřazování

Veřejné API, MCP a webová aplikace

Získání pomoci

Související