> ## Documentation Index > Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt > Use this file to discover all available pages before exploring further. # API pública heredada > Mantenga las integraciones /api/v1 existentes que intercambian una clave de acceso de API por un token de portador. 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](/es/developers/v1/quickstart) y con [Autenticación](/es/developers/v1/authentication). 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](mailto:support@livingsecurity.com). 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: 1. 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. 2. Envíe el token de portador y el ID de organización con cada solicitud a la API. Los encabezados de solicitud obligatorios son: ```http theme={null} Authorization: Bearer x-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: ```bash theme={null} npm install @livingsecurity/sdk@^1 ``` A continuación, intercambie la clave y configure el SDK: ```typescript theme={null} 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: ```bash theme={null} 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: ```json theme={null} { "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](/es/integrations/mcp) para conectar una herramienta de IA a Living Security. ## Obtener ayuda Póngase en contacto con [Soporte de Living Security](mailto:support@livingsecurity.com) 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. ## Temas relacionados Cree, rote y revoque credenciales de API. Conecte las herramientas de IA compatibles mediante Model Context Protocol. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.