> ## 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 heretada

> Mantingueu les integracions existents de /api/v1 que intercanvien una clau d'accés a l'API per un bearer token.

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](/ca/developers/v1/quickstart) i l'apartat [Autenticació](/ca/developers/v1/authentication). 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.

<Note>
  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](mailto:support@livingsecurity.com). L'identificador de l'emissor no és l'identificador de la clau d'accés ni l'identificador de l'organització.
</Note>

## 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:

1. 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ó.
2. 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:

```http theme={null}
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:

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

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

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:

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

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:

```json theme={null}
{
  "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](/ca/integrations/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](mailto:support@livingsecurity.com) 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.

## Contingut relacionat

<CardGroup cols={2}>
  <Card title="API Access Keys" icon="key" href="/ca/integrations/api-keys">
    Creeu, roteu i reviqueu credencials de l'API.
  </Card>

  <Card title="MCP Integration" icon="robot" href="/ca/integrations/mcp">
    Connecteu eines d'IA compatibles mitjançant el Model Context Protocol.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.