Inici ràpid de l'API

Creeu un compte de servei i una clau d’API al Developer Hub i, a continuació, feu la vostra primera sol·licitud. Aquest inici ràpid utilitza l’autenticació amb clau d’API; no necessiteu cap client OAuth. Consulteu Authentication si la vostra integració requereix tokens d’accés OAuth de curta durada.

Requisits previs

Accés d’administrador al Dashboard de Living Security.
El Developer Hub visible a Settings → Integrations & Developers → Developer Hub.

Creació de les credencials

Crear un compte de servei

Al Developer Hub, obriu la pestanya Service accounts i creeu un compte. Assigneu-li un nom descriptiu (per exemple, reporting-pipeline) i concediu-li els permisos que podran utilitzar les seves claus; per a aquesta guia, n’hi ha prou amb organization:read.Els permisos del compte són el límit màxim de totes les claus creades amb aquest compte: una clau mai no pot fer més del que permet el seu compte de servei.

Crear una clau d'API

Obriu la pàgina de detall del compte de servei i creeu una clau. Trieu els permisos que necessita aquesta clau en concret (un subconjunt dels del compte) i una caducitat: 30, 90 o 365 dies, o un període personalitzat. La caducitat és obligatòria.El secret de la clau comença per lsk_live_ i es mostra una sola vegada. Copieu-lo immediatament en un gestor de secrets; no es pot recuperar més endavant.

No publiqueu mai els secrets de les claus d’API al control de versions ni els incorporeu al codi del costat del client. Qualsevol persona que tingui el secret pot actuar amb els permisos de la clau.

Triar la regió

Feu la crida al host /v1 regional que correspongui a la residència de dades de l’organització. Les claus només s’autentiquen en aquest host.

Regió	URL base
EUA	`https://api.us-east-1.livingsecurity.ai/v1`
UE	`https://api.eu-west-1.livingsecurity.ai/v1`

Consulteu Regions si no esteu segurs de quin host heu d’utilitzar. Una clau vàlida enviada a l’altra regió falla com a unauthorized. Utilitzeu el menú desplegable de regió de l’exemple següent per canviar el host.

Fer la primera sol·licitud

Carregueu LIVING_SECURITY_API_KEY des del vostre gestor de secrets a l’entorn del procés que fa la sol·licitud. Els exemples següents el llegeixen sense incorporar cap secret al codi font. Per a Python, instal·leu primer requests.Feu la crida a l’API amb el secret al camp de contrasenya o al d’usuari de l’autenticació HTTP Basic; qualsevol dels dos funciona, de manera que els clients que requereixen que ambdós camps estiguin emplenats (com el connector Web de Power BI) poden posar un marcador de posició com apikey a l’altre camp.

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())

Una resposta correcta retorna la vostra organització:

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

Si obteniu aquesta resposta, les vostres credencials funcionen. La sol·licitud també apareix a la pestanya Request logs del Developer Hub en pocs instants.

L’autenticació Bearer amb el mateix secret (Authorization: Bearer lsk_live_...) també funciona. L’autenticació Basic existeix perquè les eines que només admeten usuari/contrasenya, com el connector Web de Power BI, puguin connectar-se.

Com funciona l’autenticació

La credencial determina l’organització. Les sol·licituds de /v1 no inclouen cap selector d’inquilí: ni segment de ruta d’organització ni capçalera d’organització. L’enviament d’una capçalera x-organization-id es rebutja amb invalid_request. El host ha de coincidir igualment amb la regió d’aquesta organització. Consulteu Regions.
Els permisos es comproven per operació. Cada operació de /v1 requereix un permís amb nom (per exemple, GET /v1/organization requereix organization:read). Una clau que no tingui el permís rep un 403 amb el codi insufficient_permission.
Les claus caduquen i es poden rotar sense temps d’inactivitat. Consulteu API keys per a la rotació amb un període de solapament.

Lectura de les respostes d’error

Tots els errors de /v1 són application/problem+json (RFC 9457) amb un codi llegible per màquina estable. Per exemple, una sol·licitud amb una credencial absent o desconeguda retorna:

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
}

Ramifiqueu segons code, mai segons detail. Seguiu doc_url per als passos de resolució i inclogueu request_id quan contacteu amb el suport: coincideix amb la capçalera de resposta Request-Id i amb els registres de sol·licituds del Developer Hub. El conjunt complet de codis és a la referència d’errors.

Versions del contracte

Totes les respostes retornen la versió del contracte que les ha servit a la capçalera Living-Security-Version, juntament amb una capçalera Request-Id per a la correlació. Podeu fixar una sol·licitud a una versió publicada del contracte mitjançant la 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"

La versió es resol en aquest ordre: la capçalera de la sol·licitud, si hi és; altrament, la versió per defecte fixada del compte de servei; altrament, l’última versió publicada. Sol·licitar una versió que no està publicada (o que ha superat la data de retirada) retorna un 400 amb el codi unsupported_version. Les versions publicades i els seus canvis es llisten al registre de canvis de l’API.

Resolució de problemes de la primera sol·licitud

Resultat	Acció següent
`401 unauthorized`	Comproveu el secret, la seva caducitat i la regió de l’organització. No proveu altres hosts amb una credencial activa.
`403 insufficient_permission`	Concediu `organization:read` tant al compte de servei com a la seva clau.
`400 unsupported_version`	Trieu una versió publicada al registre de canvis.
`429 rate_limited`	Espereu `Retry-After`; seguiu l’exemple de reintent limitat.
Temps d’espera de la xarxa	Comproveu la connectivitat i torneu a intentar aquesta lectura dins del pressupost de reintents de la vostra aplicació.

Per a altres errors, seguiu doc_url de la resposta. Conserveu Request-Id per al suport; no inclogueu mai la capçalera Authorization ni la vostra clau d’API en un tiquet.

Passos següents

Regions

Trieu el host /v1 dels EUA o de la UE per a l’organització.

Pagination

Recorreu les llistes amb page_token i l’embolcall de llista.

Rate limits

Enteneu els pressupostos de sol·licituds i gestioneu les respostes 429.

Error reference

Tots els codis d’error, el seu estat HTTP i com resoldre’ls.

Developer Hub

Gestioneu comptes de servei, claus d’API i registres de sol·licituds.

Centre per a desenvolupadors

API pública v1

Referència de l'API v1

Requisits previs

Creació de les credencials

Com funciona l’autenticació

Lectura de les respostes d’error

Versions del contracte

Resolució de problemes de la primera sol·licitud

Passos següents

Regions

Pagination

Rate limits

Error reference

Developer Hub

Centre per a desenvolupadors

API pública v1

Referència de l'API v1

​Requisits previs

​Creació de les credencials

​Com funciona l’autenticació

​Lectura de les respostes d’error

​Versions del contracte

​Resolució de problemes de la primera sol·licitud

​Passos següents

Regions

Pagination

Rate limits

Error reference

Developer Hub

Requisits previs

Creació de les credencials

Com funciona l’autenticació

Lectura de les respostes d’error

Versions del contracte

Resolució de problemes de la primera sol·licitud

Passos següents