API pública heretada

Aquesta guia tracta les integracions existents de /api/v1 que intercanvien una clau d’accés a l’API per un bearer token. Les seves credencials i el seu format de sol·licitud difereixen dels de l’API pública de /v1. Per a una integració nova, comenceu amb la guia d’inici ràpid de l’API i l’apartat Autenticació. La nova API de /v1 utilitza claus d’API de comptes de servei o tokens d’accés OAuth.

Abans de començar

Necessiteu:

Accés a Living Security que permeti gestionar les claus d’accés a l’API
Una clau d’accés a l’API creada a Settings → Access Keys
El secret de la clau d’accés, que es mostra una sola vegada en crear la credencial
L’identificador de l’emissor de l’API (API issuer ID) que Living Security us ha facilitat juntament amb les credencials de l’API pública
L’URL base regional de l’organització que voleu integrar
Un entorn d’execució al servidor i un gestor de secrets

Els secrets de les claus d’accés no s’han de col·locar en codi del navegador, aplicacions mòbils, control de versions, variables d’entorn del client, tiquets ni registres compartits.

El diàleg Access Keys mostra el secret d’un sol ús, però no mostra l’identificador de l’emissor de l’API (API issuer ID). Si Living Security no us ha facilitat l’identificador de l’emissor juntament amb les credencials de l’API pública, sol·liciteu-lo al servei d’assistència de Living Security. L’identificador de l’emissor no és l’identificador de la clau d’accés ni l’identificador de l’organització.

Hosts regionals

El contracte heretat utilitza aquests hosts de producció regionals de /api/v1:

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

Utilitzeu la regió assignada a l’organització de Living Security. No canvieu de regió per evitar un error d’autorització o de disponibilitat.

Recursos heretats

Recurs	Operacions compatibles
People	Cercar persones de l’organització i obtenir l’afiliació d’una persona
API access keys	Crear, llistar, rotar i revocar claus d’accés a l’API

Utilitzeu Developers → Public API Reference per consultar la llista completa d’operacions, paràmetres, sol·licituds, respostes i esquemes. Si una operació no hi és, actualment no forma part de l’API pública.

Autenticació

L’accés a l’API pública té dues etapes:

Intercanvieu la clau d’accés secreta i l’identificador de l’emissor de l’API per un bearer token de curta durada i un identificador d’organització.
Envieu el bearer token i l’identificador d’organització amb cada sol·licitud a l’API.

Les capçaleres de sol·licitud requerides són:

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

La capçalera d’organització ha de ser l’organització retornada per l’intercanvi de la clau d’accés. Una clau no autoritza l’accés a un identificador d’organització arbitrari.

SDK de TypeScript

Instal·leu la versió principal actual:

npm install @livingsecurity/sdk@^1

Després, intercanvieu la clau i configureu l’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,
});

Utilitzeu l’URL base d’EU per a una organització de la UE. L’intercanvi mitjançant l’SDK està pensat per a entorns d’execució Node.js al servidor.

Sol·licitud REST directa

Si feu l’intercanvi fora de l’SDK, envieu el bearer token i l’identificador d’organització en cada sol·licitud:

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"

Els bearer tokens són de curta durada. Torneu a intercanviar la clau d’accés quan necessiteu un token nou, en lloc de conservar un bearer token com a credencial permanent.

Cicle de vida de les claus d’accés

Poseu a les claus el nom de la integració o automatització a la qual pertanyen.
Trieu els àmbits amb menys privilegis que ofereixi el formulari de la clau d’accés.
Deseu el secret d’un sol ús immediatament; no es pot recuperar després de la creació ni de la rotació.
Roteu una clau mitjançant Settings → Access Keys i desplegueu la substitució abans de revocar la credencial antiga.
Reviqueu les claus que ja no s’utilitzin o el secret de les quals pugui haver quedat exposat.
Utilitzeu claus de compte de servei per a integracions no humanes quan aquest tipus de clau estigui disponible per a la vostra organització.

Paginació

La cerca de persones admet els paràmetres limit, cursor, offset i includeTotal. Per a un recorregut seqüencial, és preferible utilitzar el cursor retornat per la resposta anterior.

limit té un valor per defecte de 50 i accepta de 1 a 100.
cursor continua des d’una resposta anterior.
offset omet un nombre de registres i té un valor per defecte de 0.
includeTotal=true sol·licita un recompte filtrat exacte; ometeu-lo quan no necessiteu el recompte.

Llegiu l’objecte pagination retornat pel punt final. No calculeu la pàgina següent a partir del nombre de files rebudes ni combineu sol·licituds paginades de manera independent per ordenar vosaltres mateixos els resultats parcials.

Errors

Els errors JSON documentats tenen aquesta forma general:

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

message pot ser una cadena de text o una matriu de missatges de validació.

Estat	Significat	Resposta
`400`	Paràmetres o cos de la sol·licitud no vàlids	Corregiu els errors de validació indicats
`401`	El bearer token falta, no és vàlid o ha caducat	Torneu a intercanviar la clau d’accés i reintenteu-ho una vegada
`403`	La credencial no té permís o accés a l’organització	Comproveu els àmbits de la clau i el context de l’organització
`404`	El recurs no existeix a l’organització autoritzada	Verifiqueu l’identificador del recurs i l’organització
`408`	La sol·licitud ha superat el temps d’espera	Reintenteu-ho amb una espera exponencial limitada
`429`	S’ha assolit el límit de velocitat	Espereu almenys tant com indiqui `Retry-After`, si hi és
`5xx`	Fallada temporal del servei	Reintenteu les lectures segures amb una espera exponencial limitada

El contracte seleccionat actualment no publica un únic límit numèric de velocitat universal ni garanteix una capçalera de resposta amb l’identificador de la sol·licitud per a cada operació. Quan sol·liciteu assistència, inclogueu l’hora UTC, el mètode, la ruta, l’estat i el cos de la resposta sanejat. No reintenteu automàticament les operacions de creació, rotació, revocació o eliminació, tret que l’operació documenti explícitament la idempotència. Comproveu l’estat actual del recurs després d’una fallada de xarxa ambigua.

Compatibilitat i obsolescència

V1 evoluciona de manera additiva per defecte. Els clients han d’ignorar els camps de resposta desconeguts. Un canvi incompatible requereix un camí de migració documentat; les operacions obsoletes es mantenen a la referència amb el seu motiu, la substitució quan n’hi hagi i la data de retirada durant la finestra de migració. Fixeu l’SDK a una versió principal compatible i reviseu-ne les notes de la versió abans d’actualitzar. Considereu la Public API Reference generada, i no els clients d’aplicació propis, com a font de referència de l’esquema.

API pública, MCP i aplicació web

Superfície	Ús	Model de compatibilitat
Public API	Sistemes de clients, partners i automatització externa	Recursos estables i amb versions
MCP	Interaccions amb eines d’IA basades en permisos	Contractes d’eines i sortides estructurades compactes
Web application	Fluxos de treball humans al producte de Living Security	Contractes propis de l’aplicació que poden evolucionar amb la interfície

Consulteu Integració d’MCP per connectar una eina d’IA a Living Security.

Obtenir ajuda

Poseu-vos en contacte amb el servei d’assistència de Living Security i indiqueu:

Organització i regió
Nom i versió de l’SDK, si se n’utilitza un
Marca de temps UTC, mètode i ruta
Estat HTTP i cos de l’error sanejat

No inclogueu mai secrets de claus d’accés, bearer tokens ni dades privades de clients.

API pública

Referència de l'API pública

Abans de començar

Hosts regionals

Recursos heretats

Autenticació

SDK de TypeScript

Sol·licitud REST directa

Cicle de vida de les claus d’accés

Paginació

Errors

Compatibilitat i obsolescència

API pública, MCP i aplicació web

Obtenir ajuda

Contingut relacionat

API Access Keys

MCP Integration

API pública

Referència de l'API pública

​Abans de començar

​Hosts regionals

​Recursos heretats

​Autenticació

​SDK de TypeScript

​Sol·licitud REST directa

​Cicle de vida de les claus d’accés

​Paginació

​Errors

​Compatibilitat i obsolescència

​API pública, MCP i aplicació web

​Obtenir ajuda

​Contingut relacionat

API Access Keys

MCP Integration

Abans de començar

Hosts regionals

Recursos heretats

Autenticació

SDK de TypeScript

Sol·licitud REST directa

Cicle de vida de les claus d’accés

Paginació

Errors

Compatibilitat i obsolescència

API pública, MCP i aplicació web

Obtenir ajuda

Contingut relacionat