Guía de inicio rápido de la API

Cree una cuenta de servicio y una clave de API en el Developer Hub y, a continuación, realice su primera solicitud. Esta guía de inicio rápido utiliza autenticación mediante clave de API; no necesita un cliente OAuth. Consulte Autenticación si su integración requiere tokens de acceso OAuth de corta duración.

Requisitos previos

Acceso de administrador al Panel de control de Living Security.
El Developer Hub visible en Configuración → Integraciones & Developers → Developer Hub.

Crear credenciales

Crear una cuenta de servicio

En el Developer Hub, abra la pestaña Service accounts y cree una cuenta. Asígnele un nombre descriptivo (por ejemplo, reporting-pipeline) y otorgue los permisos que podrán utilizar sus claves; para esta guía, organization:read es suficiente.Los permisos de la cuenta son el límite máximo para cada clave creada bajo ella: una clave nunca puede hacer más de lo que permite su cuenta de servicio.

Crear una clave de API

Abra la página de detalles de la cuenta de servicio y cree una clave. Seleccione los permisos que necesita esta clave en concreto (un subconjunto de los de la cuenta) y una fecha de vencimiento: 30, 90 o 365 días, o un período personalizado. El vencimiento es obligatorio.El secreto de la clave comienza con lsk_live_ y se muestra una sola vez. Cópielo de inmediato en un gestor de secretos; no es posible recuperarlo después.

Nunca incluya los secretos de las claves de API en el control de versiones ni los incorpore en el código del lado del cliente. Cualquier persona que posea el secreto puede actuar con los permisos de la clave.

Elegir su región

Llame al host /v1 regional que corresponda a la residencia de datos de la organización. Las claves solo se autentican en ese host.

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

Consulte Regiones si no está seguro de qué host utilizar. Una clave válida enviada a la otra región falla con unauthorized. Utilice el menú desplegable de región del ejemplo siguiente para cambiar de host.

Realizar su primera solicitud

Cargue LIVING_SECURITY_API_KEY desde su gestor de secretos en el entorno del proceso que realiza la solicitud. Los ejemplos siguientes lo leen sin incorporar un secreto en el código fuente. Para Python, instale primero requests.Llame a la API con el secreto en el campo de contraseña o de nombre de usuario de la autenticación HTTP Basic; cualquiera de los dos funciona, de modo que los clientes que requieren que ambos campos estén completos (como el conector Web de Power BI) pueden colocar un marcador de posición como apikey en el otro campo.

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 respuesta correcta devuelve su organización:

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 obtiene esta respuesta, sus credenciales funcionan. La solicitud también aparece en la pestaña Request logs del Developer Hub en unos instantes.

La autenticación Bearer con el mismo secreto (Authorization: Bearer lsk_live_...) también funciona. Basic auth existe para que las herramientas que solo admiten nombre de usuario y contraseña, como el conector Web de Power BI, puedan conectarse.

Cómo funciona la autenticación

La credencial determina la organización. Las solicitudes a /v1 no incluyen ningún selector de inquilino: ni segmento de ruta de organización ni encabezado de organización. El envío de un encabezado x-organization-id se rechaza con invalid_request. El host debe seguir correspondiendo a la región de esa organización. Consulte Regiones.
Los permisos se comprueban por operación. Cada operación de /v1 requiere un permiso con nombre (por ejemplo, GET /v1/organization requiere organization:read). Una clave que no tenga el permiso recibe un 403 con el código insufficient_permission.
Las claves vencen y pueden rotarse sin tiempo de inactividad. Consulte Claves de API para conocer la rotación con un período de superposición.

Lectura de las respuestas de error

Todos los errores de /v1 son application/problem+json (RFC 9457) con un código de máquina estable. Por ejemplo, una solicitud con una credencial ausente o desconocida devuelve:

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
}

Base su lógica en code, nunca en detail. Siga doc_url para conocer los pasos de resolución e incluya request_id al ponerse en contacto con el soporte; coincide con el encabezado de respuesta Request-Id y con los registros de solicitudes del Developer Hub. El conjunto completo de códigos se encuentra en la referencia de errores.

Versiones del contrato

Cada respuesta devuelve la versión del contrato que la atendió en el encabezado Living-Security-Version, junto con un encabezado Request-Id para la correlación. Puede fijar una solicitud a una versión publicada del contrato mediante su fecha:

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ón se resuelve en este orden: el encabezado de la solicitud, si está presente; de lo contrario, la versión predeterminada fijada de la cuenta de servicio; y, si no, la última versión publicada. Solicitar una versión que no está publicada (o cuya fecha de retirada ya pasó) devuelve un 400 con el código unsupported_version. Las versiones publicadas y sus cambios se enumeran en el registro de cambios de la API.

Solución de problemas de su primera solicitud

Resultado	Siguiente acción
`401 unauthorized`	Compruebe el secreto, su vencimiento y la región de la organización. No pruebe otros hosts con una credencial activa.
`403 insufficient_permission`	Otorgue `organization:read` tanto a la cuenta de servicio como a su clave.
`400 unsupported_version`	Elija una versión publicada del registro de cambios.
`429 rate_limited`	Espere a `Retry-After`; siga el ejemplo de reintento acotado.
Tiempo de espera de red agotado	Compruebe la conectividad y reintente esta lectura dentro del presupuesto de reintentos de su aplicación.

Para otros errores, siga doc_url de la respuesta. Conserve Request-Id para el soporte; nunca incluya el encabezado Authorization ni su clave de API en un ticket.

Siguientes pasos

Regiones

Elija el host /v1 de EE. UU. o de la UE para la organización.

Paginación

Recorra las listas con page_token y el envoltorio de lista.

Límites de frecuencia

Comprenda los presupuestos de solicitudes y gestione las respuestas 429.

Referencia de errores

Todos los códigos de error, su estado HTTP y cómo resolverlos.

Developer Hub

Administre cuentas de servicio, claves de API y registros de solicitudes.

Centro de desarrolladores

API pública v1

Referencia de la API v1

Requisitos previos

Crear credenciales

Cómo funciona la autenticación

Lectura de las respuestas de error

Versiones del contrato

Solución de problemas de su primera solicitud

Siguientes pasos

Regiones

Paginación

Límites de frecuencia

Referencia de errores

Developer Hub

Centro de desarrolladores

API pública v1

Referencia de la API v1

​Requisitos previos

​Crear credenciales

​Cómo funciona la autenticación

​Lectura de las respuestas de error

​Versiones del contrato

​Solución de problemas de su primera solicitud

​Siguientes pasos

Regiones

Paginación

Límites de frecuencia

Referencia de errores

Developer Hub

Requisitos previos

Crear credenciales

Cómo funciona la autenticación

Lectura de las respuestas de error

Versiones del contrato

Solución de problemas de su primera solicitud

Siguientes pasos