> ## 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. # Guida rapida all'API > Creare un account di servizio e una chiave API nel Developer Hub, eseguire l'autenticazione con Basic auth ed effettuare la prima richiesta alla Public API di Living Security. Creare un account di servizio e una chiave API nel Developer Hub, quindi effettuare la prima richiesta. Questa guida rapida utilizza l'autenticazione tramite chiave API; non è necessario disporre di un client OAuth. Se l'integrazione richiede token di accesso OAuth di breve durata, consultare [Autenticazione](/it/developers/v1/authentication). ## Prerequisiti * Accesso come amministratore alla Dashboard di Living Security. * Il Developer Hub visibile in **Impostazioni → Integrazioni & Developers → Developer Hub**. ## Creare le credenziali Nel Developer Hub, aprire la scheda **Service accounts** e creare un account. Assegnargli un nome descrittivo (ad esempio `reporting-pipeline`) e concedere le autorizzazioni che le sue chiavi potranno utilizzare: per questa guida, `organization:read` è sufficiente. Le autorizzazioni dell'account rappresentano il limite massimo per ogni chiave creata al suo interno: una chiave non può mai fare più di quanto consentito dal proprio account di servizio. Aprire la pagina di dettaglio dell'account di servizio e creare una chiave. Scegliere le autorizzazioni necessarie a questa specifica chiave (un sottoinsieme di quelle dell'account) e una scadenza: 30, 90 o 365 giorni, oppure un periodo personalizzato. La scadenza è obbligatoria. Il segreto della chiave inizia con `lsk_live_` e viene mostrato **una sola volta**. Copiarlo subito in un gestore di segreti; non sarà possibile recuperarlo in seguito. Non eseguire mai il commit dei segreti delle chiavi API nel controllo di versione né inserirli nel codice lato client. Chiunque sia in possesso del segreto può agire con le autorizzazioni della chiave. Chiamare l'host regionale `/v1` corrispondente alla residenza dei dati dell'organizzazione. Le chiavi si autenticano solo su tale host. | Regione | URL di base | | - | - | | US | `https://api.us-east-1.livingsecurity.ai/v1` | | EU | `https://api.eu-west-1.livingsecurity.ai/v1` | Se non si è certi di quale host utilizzare, consultare [Regioni](/it/developers/v1/regions). Una chiave valida inviata all'altra regione restituisce l'errore `unauthorized`. Utilizzare il menu a discesa della regione nell'esempio seguente per cambiare host. Caricare `LIVING_SECURITY_API_KEY` dal gestore di segreti nell'ambiente del processo che effettua la richiesta. Gli esempi seguenti lo leggono senza inserire un segreto nel codice sorgente. Per Python, installare prima `requests`. Chiamare l'API con il segreto nel campo password o nel campo nome utente dell'autenticazione HTTP Basic: entrambi funzionano, quindi i client che richiedono la compilazione di entrambi i campi (come il connettore Web di Power BI) possono inserire un segnaposto come `apikey` nell'altro campo. ```bash cURL theme={null} 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" ``` ```bash cURL (key as username) theme={null} 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" ``` ```python Python theme={null} 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 risposta corretta restituisce la propria organizzazione: ```json Response theme={null} { "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" } ``` Se si ottiene questa risposta, le credenziali funzionano. La richiesta compare anche nella scheda **Request logs** del Developer Hub dopo pochi istanti. Funziona anche l'autenticazione Bearer con lo stesso segreto (`Authorization: Bearer lsk_live_...`). L'autenticazione Basic esiste affinché gli strumenti che supportano solo nome utente/password, come il connettore Web di Power BI, possano connettersi. ## Come funziona l'autenticazione * **La credenziale determina l'organizzazione.** Le richieste `/v1` non contengono alcun selettore del tenant: nessun segmento di percorso dell'organizzazione e nessuna intestazione dell'organizzazione. L'invio di un'intestazione `x-organization-id` viene rifiutato con `invalid_request`. L'host deve comunque corrispondere alla regione di tale organizzazione. Consultare [Regioni](/it/developers/v1/regions). * **Le autorizzazioni vengono verificate per ogni operazione.** Ogni operazione `/v1` richiede una autorizzazione specifica (ad esempio, `GET /v1/organization` richiede `organization:read`). Una chiave priva dell'autorizzazione riceve un errore `403` con codice `insufficient_permission`. * **Le chiavi scadono e possono essere ruotate senza interruzioni del servizio.** Consultare [Chiavi API](/it/developers/developer-hub/api-keys) per la rotazione con un periodo di sovrapposizione. ## Interpretare le risposte di errore Ogni errore `/v1` è `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) con un codice leggibile dalle macchine e stabile. Ad esempio, una richiesta con una credenziale mancante o sconosciuta restituisce: ```json 401 Unauthorized theme={null} { "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 } ``` Basarsi su `code`, mai su `detail`. Seguire `doc_url` per i passaggi di risoluzione e includere `request_id` quando si contatta il supporto: corrisponde all'intestazione di risposta `Request-Id` e ai log delle richieste del Developer Hub. L'insieme completo dei codici è disponibile nel [riferimento degli errori](/it/developers/v1/errors/overview). ## Versioni del contratto Ogni risposta riporta la versione del contratto che l'ha servita nell'intestazione `Living-Security-Version`, insieme a un'intestazione `Request-Id` per la correlazione. È possibile associare una richiesta a una versione del contratto pubblicata tramite la data: ```bash cURL theme={null} 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 versione viene risolta in questo ordine: l'intestazione della richiesta, se presente; altrimenti la versione predefinita fissata per l'account di servizio; altrimenti l'ultima versione pubblicata. La richiesta di una versione non pubblicata (o oltre la data di dismissione) restituisce un errore `400` con codice `unsupported_version`. Le versioni pubblicate e le relative modifiche sono elencate nel [changelog dell'API](/it/developers/v1/changelog). ## Risolvere i problemi della prima richiesta | Risultato | Azione successiva | | - | - | | `401 unauthorized` | Verificare il segreto, la sua scadenza e la regione dell'organizzazione. Non provare altri host con una credenziale attiva. | | `403 insufficient_permission` | Concedere `organization:read` sia all'account di servizio sia alla sua chiave. | | `400 unsupported_version` | Scegliere una versione pubblicata dal [changelog](/it/developers/v1/changelog). | | `429 rate_limited` | Attendere `Retry-After`; seguire l'[esempio di nuovo tentativo limitato](/it/developers/v1/rate-limits). | | Timeout di rete | Verificare la connettività e ripetere questa lettura entro il budget di nuovi tentativi dell'applicazione. | Per gli altri errori, seguire `doc_url` della risposta. Conservare `Request-Id` per il supporto; non includere mai l'intestazione Authorization né la chiave API in un ticket. ## Passaggi successivi Scegliere l'host `/v1` US o EU per l'organizzazione. Scorrere gli elenchi con `page_token` e l'envelope dell'elenco. Comprendere i budget di richieste e gestire le risposte `429`. Ogni codice di errore, il relativo stato HTTP e come risolverlo. Gestire account di servizio, chiavi API e log delle richieste. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.