API pubblica legacy

Questa guida riguarda le integrazioni /api/v1 esistenti che scambiano una chiave di accesso API con un bearer token. Le relative credenziali e il formato delle richieste differiscono da quelli dell’API pubblica /v1. Per una nuova integrazione, inizi dalla guida introduttiva all’API e da Autenticazione. La nuova API /v1 utilizza chiavi API degli account di servizio o token di accesso OAuth.

Prima di iniziare

Sono necessari:

Un accesso a Living Security che consenta la gestione delle chiavi di accesso API
Una chiave di accesso API creata in Impostazioni → Access Keys
Il segreto della chiave di accesso, mostrato una sola volta al momento della creazione della credenziale
L’ID dell’emittente API (API issuer ID) fornito da Living Security insieme alle credenziali dell’API pubblica
L’URL di base regionale dell’organizzazione che si intende integrare
Un runtime lato server e un gestore dei segreti

I segreti delle chiavi di accesso non devono essere inseriti nel codice del browser, nelle app mobili, nel controllo del codice sorgente, nelle variabili di ambiente lato client, nei ticket o nei log condivisi.

La finestra di dialogo Access Keys mostra il segreto una tantum, ma non mostra l’ID dell’emittente API. Se Living Security non Le ha fornito l’ID dell’emittente insieme alle credenziali dell’API pubblica, lo richieda al supporto di Living Security. L’ID dell’emittente non coincide con l’ID della chiave di accesso né con l’ID dell’organizzazione.

Host regionali

Il contratto legacy utilizza i seguenti host di produzione regionali /api/v1:

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

Utilizzi la regione assegnata all’organizzazione Living Security. Non cambi regione per aggirare un errore di autorizzazione o di disponibilità.

Risorse legacy

Risorsa	Operazioni supportate
Persone	Cercare le persone dell’organizzazione e recuperare l’appartenenza di una persona
Chiavi di accesso API	Creare, elencare, ruotare e revocare le chiavi di accesso API

Utilizzi Developers → Public API Reference per l’elenco completo di operazioni, parametri, richieste, risposte e schemi. Se un’operazione non è presente, attualmente non fa parte dell’API pubblica.

Autenticazione

L’accesso all’API pubblica prevede due fasi:

Scambiare la chiave di accesso segreta e l’ID dell’emittente API con un bearer token di breve durata e un ID dell’organizzazione.
Inviare il bearer token e l’ID dell’organizzazione con ogni richiesta API.

Le intestazioni di richiesta obbligatorie sono:

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

L’intestazione dell’organizzazione deve contenere l’organizzazione restituita dallo scambio della chiave di accesso. Una chiave non autorizza l’accesso a un ID organizzazione arbitrario.

SDK TypeScript

Installi la versione major corrente:

npm install @livingsecurity/sdk@^1

Quindi scambi la chiave e configuri 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,
});

Utilizzi l’URL di base EU per un’organizzazione EU. Lo scambio tramite SDK è pensato per runtime Node.js lato server.

Richiesta REST diretta

Se esegue lo scambio senza l’SDK, invii il bearer token e l’ID dell’organizzazione con ogni richiesta:

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"

I bearer token hanno breve durata. Per ottenere un nuovo token, scambi nuovamente la chiave di accesso anziché conservare un bearer token come credenziale permanente.

Ciclo di vita delle chiavi di accesso

Assegni alle chiavi il nome dell’integrazione o dell’automazione a cui appartengono.
Scelga gli ambiti (scope) con i privilegi minimi offerti dal modulo della chiave di accesso.
Memorizzi immediatamente il segreto mostrato una sola volta: non può essere recuperato dopo la creazione o la rotazione.
Ruoti una chiave tramite Impostazioni → Access Keys e distribuisca la nuova credenziale prima di revocare quella precedente.
Revochi le chiavi non più utilizzate o il cui segreto potrebbe essere stato esposto.
Utilizzi chiavi degli account di servizio per le integrazioni non umane, quando questo tipo di chiave è disponibile per la Sua organizzazione.

Paginazione

La ricerca delle persone supporta i parametri limit, cursor, offset e includeTotal. Per una scansione sequenziale, preferisca il cursore restituito dalla risposta precedente.

limit ha come valore predefinito 50 e accetta valori da 1 a 100.
cursor prosegue a partire da una risposta precedente.
offset salta un determinato numero di record e ha come valore predefinito 0.
includeTotal=true richiede un conteggio esatto dei risultati filtrati; lo ometta se il conteggio non è necessario.

Legga l’oggetto pagination restituito dall’endpoint. Non calcoli la pagina successiva in base al numero di righe ricevute e non combini richieste paginate in modo indipendente ordinando autonomamente i risultati parziali.

Errori

Gli errori JSON documentati hanno la seguente struttura generale:

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

message può essere una stringa o un array di messaggi di convalida.

Stato	Significato	Risposta
`400`	Parametri o corpo della richiesta non validi	Corregga gli errori di convalida indicati
`401`	Il bearer token è mancante, non valido o scaduto	Scambi di nuovo la chiave di accesso e riprovi una volta
`403`	La credenziale non dispone di autorizzazioni o dell’accesso all’organizzazione	Verifichi gli ambiti della chiave e il contesto dell’organizzazione
`404`	La risorsa non esiste nell’organizzazione autorizzata	Verifichi l’ID della risorsa e l’organizzazione
`408`	Timeout della richiesta	Riprovi con backoff esponenziale limitato
`429`	Limite di frequenza raggiunto	Attenda almeno quanto indicato in `Retry-After`, se presente
`5xx`	Errore temporaneo del servizio	Riprovi le letture sicure con backoff esponenziale limitato

Il contratto curato non pubblica attualmente un unico limite di frequenza numerico universale né garantisce un’intestazione di risposta con l’ID della richiesta per ogni operazione. Quando contatta il supporto, indichi data e ora UTC, metodo, percorso, stato e corpo della risposta sanificato. Non riprovi automaticamente le operazioni di creazione, rotazione, revoca o eliminazione, a meno che l’operazione non documenti esplicitamente l’idempotenza. Dopo un errore di rete ambiguo, verifichi lo stato corrente della risorsa.

Compatibilità e deprecazione

La V1 evolve in modo additivo per impostazione predefinita. I client devono ignorare i campi di risposta sconosciuti. Una modifica non retrocompatibile richiede un percorso di migrazione documentato; le operazioni deprecate restano nel riferimento con il relativo motivo, la sostituzione, se disponibile, e la data di dismissione durante il periodo di migrazione. Vincoli l’SDK a una versione major compatibile e consulti le note di rilascio prima di eseguire l’aggiornamento. Consideri il Public API Reference generato, e non i client delle app proprietarie, come fonte di riferimento per lo schema.

API pubblica, MCP e applicazione web

Superficie	Utilizzo	Modello di compatibilità
API pubblica	Sistemi dei clienti, partner e automazione esterna	Risorse stabili e con versioni
MCP	Interazioni con strumenti di IA basate su autorizzazioni	Contratti degli strumenti e output strutturati compatti
Applicazione web	Flussi di lavoro umani nel prodotto Living Security	Contratti gestiti dall’app che possono evolvere con l’interfaccia

Consulti Integrazione MCP per collegare uno strumento di IA a Living Security.

Assistenza

Contatti il supporto di Living Security fornendo:

Organizzazione e regione
Nome e versione dell’SDK, se utilizzato
Timestamp UTC, metodo e percorso
Stato HTTP e corpo dell’errore sanificato

Non includa mai segreti delle chiavi di accesso, bearer token o dati privati dei clienti.

API pubblica

Riferimento API pubblica

Prima di iniziare

Host regionali

Risorse legacy

Autenticazione

SDK TypeScript

Richiesta REST diretta

Ciclo di vita delle chiavi di accesso

Paginazione

Errori

Compatibilità e deprecazione

API pubblica, MCP e applicazione web

Assistenza

Argomenti correlati

Chiavi di accesso API

Integrazione MCP

API pubblica

Riferimento API pubblica

​Prima di iniziare

​Host regionali

​Risorse legacy

​Autenticazione

​SDK TypeScript

​Richiesta REST diretta

​Ciclo di vita delle chiavi di accesso

​Paginazione

​Errori

​Compatibilità e deprecazione

​API pubblica, MCP e applicazione web

​Assistenza

​Argomenti correlati

Chiavi di accesso API

Integrazione MCP

Prima di iniziare

Host regionali

Risorse legacy

Autenticazione

SDK TypeScript

Richiesta REST diretta

Ciclo di vita delle chiavi di accesso

Paginazione

Errori

Compatibilità e deprecazione

API pubblica, MCP e applicazione web

Assistenza

Argomenti correlati