Guida rapida all'API

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.

Prerequisiti

Accesso come amministratore alla Dashboard di Living Security.
Il Developer Hub visibile in Impostazioni → Integrazioni & Developers → Developer Hub.

Creare le credenziali

Creare un account di servizio

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.

Creare una chiave API

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.

Scegliere la regione

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. Una chiave valida inviata all’altra regione restituisce l’errore unauthorized. Utilizzare il menu a discesa della regione nell’esempio seguente per cambiare host.

Effettuare la prima richiesta

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.

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 risposta corretta restituisce la propria organizzazione:

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

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.
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 per la rotazione con un periodo di sovrapposizione.

Interpretare le risposte di errore

Ogni errore /v1 è application/problem+json (RFC 9457) con un codice leggibile dalle macchine e stabile. Ad esempio, una richiesta con una credenziale mancante o sconosciuta restituisce:

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
}

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.

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:

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.

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.
`429 rate_limited`	Attendere `Retry-After`; seguire l’esempio di nuovo tentativo limitato.
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

Regioni

Scegliere l’host /v1 US o EU per l’organizzazione.

Paginazione

Scorrere gli elenchi con page_token e l’envelope dell’elenco.

Limiti di frequenza

Comprendere i budget di richieste e gestire le risposte 429.

Riferimento degli errori

Ogni codice di errore, il relativo stato HTTP e come risolverlo.

Developer Hub

Gestire account di servizio, chiavi API e log delle richieste.

Hub per sviluppatori

API pubblica v1

Riferimento API v1

Prerequisiti

Creare le credenziali

Come funziona l’autenticazione

Interpretare le risposte di errore

Versioni del contratto

Risolvere i problemi della prima richiesta

Passaggi successivi

Regioni

Paginazione

Limiti di frequenza

Riferimento degli errori

Developer Hub

Hub per sviluppatori

API pubblica v1

Riferimento API v1

​Prerequisiti

​Creare le credenziali

​Come funziona l’autenticazione

​Interpretare le risposte di errore

​Versioni del contratto

​Risolvere i problemi della prima richiesta

​Passaggi successivi

Regioni

Paginazione

Limiti di frequenza

Riferimento degli errori

Developer Hub

Prerequisiti

Creare le credenziali

Come funziona l’autenticazione

Interpretare le risposte di errore

Versioni del contratto

Risolvere i problemi della prima richiesta

Passaggi successivi