> ## 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 pubblica legacy > Gestisca le integrazioni /api/v1 esistenti che scambiano una chiave di accesso API con un bearer token. 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](/it/developers/v1/quickstart) e da [Autenticazione](/it/developers/v1/authentication). 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](mailto:support@livingsecurity.com). 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: 1. Scambiare la chiave di accesso segreta e l'ID dell'emittente API con un bearer token di breve durata e un ID dell'organizzazione. 2. Inviare il bearer token e l'ID dell'organizzazione con ogni richiesta API. Le intestazioni di richiesta obbligatorie sono: ```http theme={null} Authorization: Bearer x-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: ```bash theme={null} npm install @livingsecurity/sdk@^1 ``` Quindi scambi la chiave e configuri 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, }); ``` 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: ```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" ``` 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: ```json theme={null} { "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](/it/integrations/mcp) per collegare uno strumento di IA a Living Security. ## Assistenza Contatti il [supporto di Living Security](mailto:support@livingsecurity.com) 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. ## Argomenti correlati Crei, ruoti e revochi le credenziali API. Colleghi gli strumenti di IA supportati tramite Model Context Protocol. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.