API pública heredada

Esta guía describe las integraciones /api/v1 existentes que intercambian una clave de acceso de API por un token de portador. Sus credenciales y el formato de las solicitudes difieren de los de la API pública /v1. Para una nueva integración, comience con la guía de inicio rápido de la API y con Autenticación. La nueva API /v1 utiliza claves de API de cuentas de servicio o tokens de acceso OAuth.

Antes de comenzar

Necesita lo siguiente:

Acceso a Living Security que permita administrar claves de acceso de API
Una clave de acceso de API creada en Configuración → Access Keys
El secreto de la clave de acceso, que se muestra una sola vez al crear la credencial
El ID de emisor de la API que Living Security proporciona junto con sus credenciales de la API pública
La URL base regional de la organización que va a integrar
Un entorno de ejecución del lado del servidor y un administrador de secretos

Los secretos de las claves de acceso no deben colocarse en código de navegador, aplicaciones móviles, control de código fuente, variables de entorno del lado del cliente, tickets ni registros compartidos.

El cuadro de diálogo Access Keys muestra el secreto de un solo uso, pero no muestra el ID de emisor de la API. Si Living Security no le ha proporcionado el ID de emisor junto con sus credenciales de la API pública, solicítelo a Soporte de Living Security. El ID de emisor no es el ID de la clave de acceso ni el ID de la organización.

Hosts regionales

El contrato heredado utiliza los siguientes hosts regionales de producción /api/v1:

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

Utilice la región asignada a la organización de Living Security. No cambie de región para sortear un error de autorización o de disponibilidad.

Recursos heredados

Recurso	Operaciones compatibles
Personas	Buscar personas de la organización y obtener la pertenencia de una persona
Claves de acceso de API	Crear, enumerar, rotar y revocar claves de acceso de API

Utilice Developers → Public API Reference para consultar la lista completa de operaciones, parámetros, solicitudes, respuestas y esquemas. Si una operación no aparece allí, actualmente no forma parte de la API pública.

Autenticación

El acceso a la API pública consta de dos etapas:

Intercambie el secreto de la clave de acceso y el ID de emisor de la API por un token de portador de corta duración y un ID de organización.
Envíe el token de portador y el ID de organización con cada solicitud a la API.

Los encabezados de solicitud obligatorios son:

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

El encabezado de la organización debe corresponder a la organización devuelta por el intercambio de la clave de acceso. Una clave no autoriza el acceso a un ID de organización arbitrario.

SDK de TypeScript

Instale la versión principal actual:

npm install @livingsecurity/sdk@^1

A continuación, intercambie la clave y configure el 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,
});

Utilice la URL base de la UE para una organización de la UE. El intercambio mediante el SDK está pensado para entornos de ejecución Node.js del lado del servidor.

Solicitud REST directa

Si realiza el intercambio fuera del SDK, envíe el token de portador y el ID de organización en cada solicitud:

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"

Los tokens de portador son de corta duración. Vuelva a intercambiar la clave de acceso para obtener un nuevo token, en lugar de conservar un token de portador como credencial permanente.

Ciclo de vida de las claves de acceso

Asigne a las claves el nombre de la integración o automatización a la que pertenecen.
Elija los ámbitos con menos privilegios que ofrezca el formulario de claves de acceso.
Almacene el secreto de un solo uso de inmediato; no se puede recuperar después de la creación ni de la rotación.
Rote una clave desde Configuración → Access Keys e implemente la sustituta antes de revocar la credencial anterior.
Revoque las claves que ya no se utilicen o cuyo secreto pueda haberse expuesto.
Utilice claves de cuenta de servicio para integraciones no humanas cuando ese tipo de clave esté disponible para su organización.

Paginación

La búsqueda de personas admite los parámetros limit, cursor, offset y includeTotal. Para un recorrido secuencial, se recomienda usar el cursor devuelto por la respuesta anterior.

limit tiene un valor predeterminado de 50 y acepta de 1 a 100.
cursor continúa a partir de una respuesta anterior.
offset omite un número de registros y tiene un valor predeterminado de 0.
includeTotal=true solicita un recuento exacto filtrado; omítalo cuando no necesite el recuento.

Lea el objeto pagination devuelto por el punto de conexión. No calcule la página siguiente a partir del número de filas recibidas ni combine solicitudes paginadas de forma independiente para ordenar usted mismo los resultados parciales.

Errores

Los errores JSON documentados tienen la siguiente estructura general:

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

message puede ser una cadena o una matriz de mensajes de validación.

Estado	Significado	Respuesta
`400`	Parámetros o cuerpo de la solicitud no válidos	Corrija los errores de validación indicados
`401`	El token de portador falta, no es válido o ha caducado	Vuelva a intercambiar la clave de acceso y reintente una vez
`403`	La credencial carece de permisos o de acceso a la organización	Compruebe los ámbitos de la clave y el contexto de la organización
`404`	El recurso no existe en la organización autorizada	Verifique el ID del recurso y la organización
`408`	Se agotó el tiempo de espera de la solicitud	Reintente con retroceso exponencial acotado
`429`	Se alcanzó el límite de velocidad	Espere al menos el tiempo indicado en `Retry-After`, cuando esté presente
`5xx`	Fallo temporal del servicio	Reintente las lecturas seguras con retroceso exponencial acotado

El contrato seleccionado no publica actualmente un límite de velocidad numérico universal ni garantiza un encabezado de respuesta con el ID de solicitud para todas las operaciones. Al solicitar soporte, registre la hora UTC, el método, la ruta, el estado y el cuerpo de la respuesta depurado. No reintente automáticamente las operaciones de creación, rotación, revocación o eliminación, a menos que la operación documente explícitamente la idempotencia. Compruebe el estado actual del recurso después de un fallo de red ambiguo.

Compatibilidad y obsolescencia

V1 evoluciona de forma aditiva de manera predeterminada. Los clientes deben ignorar los campos de respuesta desconocidos. Un cambio incompatible requiere una ruta de migración documentada; las operaciones obsoletas permanecen en la referencia con su motivo, su sustituto cuando exista y su fecha de retirada durante el periodo de migración. Fije el SDK a una versión principal compatible y revise sus notas de la versión antes de actualizar. Considere la referencia de la API pública generada, y no los clientes de aplicaciones propias, como la fuente de referencia del esquema.

API pública, MCP y aplicación web

Superficie	Uso	Modelo de compatibilidad
API pública	Sistemas de clientes, socios y automatización externa	Recursos estables y con control de versiones
MCP	Interacciones con herramientas de IA basadas en permisos	Contratos de herramientas y salidas estructuradas compactas
Aplicación web	Flujos de trabajo humanos en el producto Living Security	Contratos propios de la aplicación que pueden evolucionar con la interfaz

Consulte Integración de MCP para conectar una herramienta de IA a Living Security.

Obtener ayuda

Póngase en contacto con Soporte de Living Security e incluya lo siguiente:

Organización y región
Nombre y versión del SDK, si lo utiliza
Marca de tiempo UTC, método y ruta
Estado HTTP y cuerpo del error depurado

No incluya nunca secretos de claves de acceso, tokens de portador ni datos privados de clientes.

API pública

Referencia de la API pública

Antes de comenzar

Hosts regionales

Recursos heredados

Autenticación

SDK de TypeScript

Solicitud REST directa

Ciclo de vida de las claves de acceso

Paginación

Errores

Compatibilidad y obsolescencia

API pública, MCP y aplicación web

Obtener ayuda

Temas relacionados

Claves de acceso de API

Integración de MCP

API pública

Referencia de la API pública

​Antes de comenzar

​Hosts regionales

​Recursos heredados

​Autenticación

​SDK de TypeScript

​Solicitud REST directa

​Ciclo de vida de las claves de acceso

​Paginación

​Errores

​Compatibilidad y obsolescencia

​API pública, MCP y aplicación web

​Obtener ayuda

​Temas relacionados

Claves de acceso de API

Integración de MCP

Antes de comenzar

Hosts regionales

Recursos heredados

Autenticación

SDK de TypeScript

Solicitud REST directa

Ciclo de vida de las claves de acceso

Paginación

Errores

Compatibilidad y obsolescencia

API pública, MCP y aplicación web

Obtener ayuda

Temas relacionados