> ## 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.

# Credenziali client OAuth

> Effettuare il provisioning di un client di service account con ambito limitato, gestire i secret monouso e ripristinare in modo sicuro lo stato dopo richieste dall'esito incerto.

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](/it/developers/v1/authentication) per scegliere
tra i due metodi e comprendere il ruolo dei service account.

<Note>
  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.
</Note>

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](/it/developers/developer-hub/service-accounts) 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](/it/developers/v1/regions) 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 Python theme={null}
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](/it/developers/v1/errors/overview) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.