Credenziali client OAuth

Utilizzare le credenziali client OAuth quando l’integrazione backend richiede token di accesso di breve durata oppure quando lo prevede la policy di sicurezza. Ogni client appartiene a un solo service account e a una sola organizzazione. OAuth è facoltativo: una chiave API con ambito limitato è sufficiente per un’integrazione server privata in grado di archiviare e ruotare in modo sicuro una chiave. Consultare Autenticazione per scegliere tra i due metodi e comprendere il ruolo dei service account.

L’accesso OAuth deve essere abilitato per la propria organizzazione. La configurazione iniziale fornisce l’endpoint dei token regionale, l’issuer, l’audience e il metodo di autenticazione del client. Se sono necessarie queste impostazioni o non è possibile accedere alla gestione dei client, contattare il supporto di Living Security.

Il grant client credentials rappresenta il service account. Non effettua l’accesso di una persona né richiede a un cliente di autorizzare un’applicazione. L’autorizzazione delegata tramite browser è una funzionalità OAuth distinta e non è offerta da queste operazioni.

Prima di iniziare

Creare un service account con i soli permessi necessari all’integrazione.
Utilizzare una credenziale di gestione con service_account:manage e ciascun permesso che si desidera concedere al nuovo client. Anche l’account di destinazione deve possedere tali permessi. Un client non può estendere l’autorità di nessuno dei due account.
Scegliere la regione dell’organizzazione. Le credenziali API e i token di accesso OAuth devono essere utilizzati sull’host API regionale corrispondente.
Conservare il secret del client e i token nell’archivio dei secret lato server. Non inserirli mai nel codice del browser, nelle applicazioni mobili, nel controllo del codice sorgente o nei log delle richieste.

Creare un client

POST /v1/oauth_clients richiede service_account_id, un elenco non vuoto di scopes espliciti e un Idempotency-Key. I caratteri jolly non sono accettati. Un client supporta fino a 100 scope, con una lunghezza complessiva massima di 4.096 caratteri. Ogni service account può avere al massimo 20 client oppure operazioni di creazione/pulizia non risolte. La revoca nega immediatamente l’accesso alle API. Un client o una creazione incerta presso il provider continua a essere conteggiato nel limite finché la pulizia remota non viene confermata. Una prenotazione abbandonata o una creazione di cui sia provato il fallimento prima dell’avvio dell’attività presso il provider può liberare in sicurezza il proprio slot. La relativa chiave di retry appartiene comunque al tentativo originale; recuperare quella ricevuta prima di decidere se creare un sostituto. Scegliere una chiave di retry per questo tentativo di creazione e renderla persistente prima di inviare la richiesta. Utilizzare da 1 a 255 caratteri ASCII visibili, senza spazi. Riutilizzarla con lo stesso account, gli stessi scope, la stessa entità di gestione, la stessa regione e la stessa versione API dopo una risposta persa. La rotazione della credenziale di gestione sotto lo stesso service account non crea una nuova identità di retry. Installare il pacchetto requests di Python. Caricare i seguenti valori di ambiente tramite la normale gestione di secret e configurazione:

Variabile	Valore
`LIVING_SECURITY_API_KEY`	Chiave API di gestione
`LIVING_SECURITY_REGION`	`us` o `eu`
`LIVING_SECURITY_SERVICE_ACCOUNT_ID`	ID del service account di destinazione
`LIVING_SECURITY_OAUTH_CREATE_KEY`	Chiave di retry salvata in precedenza

Python

import os
import requests

HOSTS = {
    "us": "https://api.us-east-1.livingsecurity.ai/v1",
    "eu": "https://api.eu-west-1.livingsecurity.ai/v1",
}
base = HOSTS[os.environ["LIVING_SECURITY_REGION"]]
response = requests.post(
    f"{base}/oauth_clients",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={
        "Living-Security-Version": "2026-07-01",
        "Idempotency-Key": os.environ["LIVING_SECURITY_OAUTH_CREATE_KEY"],
    },
    json={
        "service_account_id": os.environ["LIVING_SECURITY_SERVICE_ACCOUNT_ID"],
        "scopes": ["organization:read"],
    },
    timeout=(5, 30),
    allow_redirects=False,
)
try:
    if response.status_code != 201:
        raise RuntimeError(
            f"Client creation needs review: HTTP {response.status_code}; "
            f"request_id={response.headers.get('Request-Id', 'unknown')}"
        )
    client = response.json()
    if client.get("object") != "oauth_client" or not client.get("id"):
        raise RuntimeError("Unexpected client receipt; preserve the retry key")
    if client.get("status") != "active" or not client.get("client_secret"):
        raise RuntimeError(
            f"Client {client['id']} needs recovery; no usable secret was returned"
        )
    # Persist client['id'], client['client_id'], and client['client_secret']
    # directly in your secret manager before using the client. Do not print them.
finally:
    response.close()

L’esempio effettua una sola richiesta e conserva il risultato in memoria. Aggiungere l’operazione di scrittura del proprio secret manager nel punto indicato prima di eseguirlo in produzione. L’esempio richiede volutamente una decisione dopo un risultato incerto, anziché creare silenziosamente un altro client. Anche le eccezioni di rete richiedono i passaggi di ripristino descritti di seguito. Le risposte di creazione e di ricevuta utilizzano 201 e contengono una risorsa oauth_client con id, service_account_id, client_id, scopes, status, created_at e client_secret. Le risposte sono contrassegnate come Cache-Control: no-store.

id identifica la risorsa della piattaforma. Salvarlo per il recupero e la revoca.
client_id identifica il client durante lo scambio del token. Non è l’ID della risorsa della piattaforma. Può essere null mentre la creazione è in sospeso.
client_secret viene restituito solo alla richiesta che completa la creazione. Ogni richiesta di creazione ripetuta restituisce null, incluso un retry dopo una risposta di successo andata persa. Il recupero non restituisce mai un secret.

Ripristinare dopo una risposta persa o interrotta

Ripetere la stessa richiesta di creazione con la chiave di retry salvata per recuperare una ricevuta della risorsa. La ricevuta riflette lo stato corrente, quindi un client revocato rimane revocato. Questa operazione non utilizza il contratto generale di replay delle risposte in cache di 24 ore e non restituisce un’intestazione Idempotent-Replayed.

Risultato	Azione successiva
`active`, secret presente	Salvare il secret in modo sicuro e proseguire con l’onboarding.
`active`, secret assente	Il secret non può essere recuperato. Revocare questo client, confermare la revoca, quindi creare un sostituto utilizzando una nuova chiave di retry.
`pending`	La creazione non è confermata. Mantenere la stessa chiave di retry. Recuperare la risorsa per verificarne lo stato; non creare duplicati per aggirare l’incertezza.
`revoked`, `disabled` o `expired`	Non utilizzare questo client. Confermare la configurazione dell’account previsto prima di effettuare il provisioning di un sostituto.
`409 idempotency_key_reuse`	La richiesta è cambiata con una chiave esistente. Recuperare l’operazione originale prima di decidere se sia necessaria una creazione distinta.
`409 invalid_request`	Verificare lo stato e i grant dell’account di destinazione. Se è stato raggiunto il limite di client, completare la pulizia prima di riprovare; cambiare la chiave di retry non libera capacità.
`429`	Rispettare `Retry-After`; conservare la stessa chiave e la stessa richiesta.
`500`, `503` o un timeout di rete	L’esito potrebbe essere sconosciuto. Conservare la chiave e i dati di input; recuperare la ricevuta prima di creare un altro client.
`401` o `403`	Risolvere i problemi di accesso relativi a credenziali, permessi o entitlement prima di riprovare.
`404`	Verificare l’abilitazione di OAuth, l’host regionale e la proprietà della risorsa.

Consultare errori per gli ID delle richieste e i dettagli sul ripristino. Non inviare mai un secret del client o un token di accesso con una richiesta al supporto.

Verificare e revocare

Utilizzare la credenziale di gestione e la risorsa della piattaforma id:

Operazione	Richiesta	Esito positivo
Verificare lo stato corrente	`GET /v1/oauth_clients/{id}`	`200`, risorsa client senza secret
Revocare l’accesso	`DELETE /v1/oauth_clients/{id}`	`200`, risorsa client revocata senza secret

La revoca blocca le richieste API successive del client, incluse quelle effettuate con token già emessi. Non annulla le attività già accettate dall’API. La pulizia remota delle credenziali può completarsi in un secondo momento. Ripetere la revoca è sicuro e non richiede una chiave di retry. Continuare a utilizzare la credenziale di gestione se il client da revocare è esso stesso un chiamante API.

Ruotare senza perdere l’accesso

Creare un secondo client con il limite di scope richiesto. Salvarne il secret, ottenere un token tramite l’endpoint dei token regionale e verificare che l’integrazione funzioni con esso. Passare l’integrazione al client sostitutivo, quindi revocare la vecchia risorsa. Conservare una credenziale di gestione indipendente per poter ripristinare lo stato in caso di rollout errato. I token di accesso non possono concedere più degli scope del client e dei permessi correnti del service account. La rimozione dei permessi dell’account o la revoca di un client ha la precedenza sulla durata residua di un token. Non considerare un token in cache come prova che l’autorizzazione sia ancora valida. Ottenere un nuovo token di accesso prima della scadenza autenticando nuovamente il client; questo grant non utilizza refresh token.

Hub per sviluppatori

API pubblica v1

Riferimento API v1

Prima di iniziare

Creare un client

Ripristinare dopo una risposta persa o interrotta

Verificare e revocare

Ruotare senza perdere l’accesso

Hub per sviluppatori

API pubblica v1

Riferimento API v1

​Prima di iniziare

​Creare un client

​Ripristinare dopo una risposta persa o interrotta

​Verificare e revocare

​Ruotare senza perdere l’accesso

Prima di iniziare

Creare un client

Ripristinare dopo una risposta persa o interrotta

Verificare e revocare

Ruotare senza perdere l’accesso