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

# Identifiants client OAuth

> Provisionnez un client de compte de service à portée restreinte, gérez les secrets à usage unique et reprenez en toute sécurité après des requêtes dont le résultat est incertain.

Utilisez les identifiants client OAuth lorsque votre intégration backend nécessite des jetons d'accès de courte durée
ou lorsque votre politique de sécurité l'exige. Chaque client appartient à
un compte de service et à une organisation. **OAuth est facultatif :** une clé
d'API à portée restreinte suffit pour une intégration serveur privée capable de stocker
et de renouveler une clé en toute sécurité. Consultez [Authentification](/fr/developers/v1/authentication) pour choisir
entre les deux méthodes et comprendre comment s'intègrent les comptes de service.

<Note>
  L'accès OAuth doit être activé pour votre organisation. Votre configuration fournit
  le point de terminaison de jeton régional, l'émetteur, l'audience et la méthode d'authentification du client.
  Si vous avez besoin de ces paramètres ou si vous ne pouvez pas accéder à la gestion des clients, contactez
  l'assistance de Living Security.
</Note>

L'octroi d'identifiants client représente votre compte de service. Il ne connecte aucune personne
et ne demande pas à un client d'autoriser une application. L'autorisation déléguée via un
navigateur est une fonctionnalité OAuth distincte et n'est pas proposée par ces opérations.

## Avant de commencer

* Créez un [compte de service](/fr/developers/developer-hub/service-accounts) disposant uniquement des
  autorisations nécessaires à l'intégration.
* Utilisez un identifiant de gestion disposant de `service_account:manage` et de chaque autorisation
  que vous souhaitez accorder au nouveau client. Le compte cible doit également détenir ces
  autorisations. Un client ne peut étendre les droits d'aucun des deux comptes.
* Choisissez la [région](/fr/developers/v1/regions) de l'organisation. Les identifiants d'API et
  les jetons d'accès OAuth doivent être utilisés sur l'hôte d'API régional correspondant.
* Conservez le secret du client et les jetons dans votre stockage de secrets côté serveur. Ne les placez jamais
  dans du code de navigateur, des applications mobiles, un système de contrôle de version ou des journaux de requêtes.

## Créer un client

`POST /v1/oauth_clients` requiert `service_account_id`, une liste non vide de
`scopes` explicites et un `Idempotency-Key`. Les caractères génériques ne sont pas acceptés. Un client prend en charge
jusqu'à 100 portées, d'une longueur cumulée maximale de 4 096 caractères. Chaque compte de service
peut avoir au plus 20 clients ou opérations de création/nettoyage non résolues.
La révocation refuse immédiatement l'accès à l'API. Un client ou une création incertaine
auprès du fournisseur continue de compter dans la limite jusqu'à ce que le nettoyage à distance soit confirmé.
Une réservation abandonnée ou une création dont l'échec avant tout traitement par le fournisseur est avéré
peut libérer son emplacement en toute sécurité. Sa clé de nouvelle tentative reste associée à la tentative initiale ;
récupérez ce reçu avant de décider de créer un remplaçant.

Choisissez une clé de nouvelle tentative pour cette tentative de création et conservez-la de façon persistante **avant** d'envoyer
la requête. Utilisez de 1 à 255 caractères ASCII visibles, sans espaces. Réutilisez-la avec
le même compte, les mêmes portées, le même principal de gestion, la même région et la même version d'API après une
réponse perdue. Renouveler l'identifiant de gestion sous le même compte de service
ne crée pas de nouvelle identité de nouvelle tentative.

Installez le package Python `requests`. Chargez les valeurs d'environnement suivantes via
votre gestion habituelle des secrets et de la configuration :

| Variable | Valeur |
| - | - |
| `LIVING_SECURITY_API_KEY` | Clé d'API de gestion |
| `LIVING_SECURITY_REGION` | `us` ou `eu` |
| `LIVING_SECURITY_SERVICE_ACCOUNT_ID` | ID du compte de service cible |
| `LIVING_SECURITY_OAUTH_CREATE_KEY` | Clé de nouvelle tentative précédemment conservée |

```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'exemple effectue une seule requête et conserve le résultat en mémoire. Ajoutez l'opération d'écriture
de votre gestionnaire de secrets à l'endroit indiqué avant de l'exécuter en production.
Il exige volontairement une décision après un résultat incertain au lieu de
créer silencieusement un autre client. Les exceptions réseau nécessitent également les étapes de reprise ci-dessous.

Les réponses de création et de reçu utilisent `201` et contiennent une ressource `oauth_client`
avec `id`, `service_account_id`, `client_id`, `scopes`, `status`, `created_at` et
`client_secret`. Les réponses sont marquées `Cache-Control: no-store`.

* **`id`** identifie la ressource de la plateforme. Enregistrez-le pour la récupération et la révocation.
* **`client_id`** identifie le client lors de l'échange de jetons. Il ne s'agit pas de l'ID de
  ressource de la plateforme. Il peut valoir `null` tant que la création est en attente.
* **`client_secret`** n'est renvoyé qu'à la requête qui finalise la création.
  Toute requête de création répétée renvoie `null`, y compris une nouvelle tentative après une réponse de
  succès perdue. La récupération ne renvoie jamais de secret.

## Reprendre après une réponse perdue ou interrompue

Répétez la même requête de création avec la clé de nouvelle tentative enregistrée pour récupérer un reçu de
ressource. Le reçu reflète l'état actuel ; un client révoqué reste donc révoqué.
Cette opération n'utilise pas le contrat général de relecture de réponse en cache de 24 heures
et ne renvoie pas d'en-tête `Idempotent-Replayed`.

| Résultat | Action suivante |
| - | - |
| `active`, secret présent | Enregistrez le secret de manière sécurisée et poursuivez l'intégration. |
| `active`, secret absent | Le secret ne peut pas être récupéré. Révoquez ce client, confirmez la révocation, puis créez un remplaçant avec une nouvelle clé de nouvelle tentative. |
| `pending` | La création n'est pas confirmée. Conservez la même clé de nouvelle tentative. Récupérez la ressource pour en inspecter l'état ; ne créez pas de doublons pour contourner l'incertitude. |
| `revoked`, `disabled` ou `expired` | N'utilisez pas ce client. Confirmez la configuration prévue du compte avant de provisionner un remplaçant. |
| `409 idempotency_key_reuse` | La requête a été modifiée sous une clé existante. Récupérez l'opération d'origine avant de décider si une création distincte est nécessaire. |
| `409 invalid_request` | Vérifiez l'état et les autorisations du compte cible. Si sa limite de clients a été atteinte, effectuez le nettoyage avant de réessayer ; changer la clé de nouvelle tentative ne libère pas de capacité. |
| `429` | Respectez `Retry-After` ; conservez la même clé et la même requête. |
| `500`, `503` ou un délai d'attente réseau dépassé | Le résultat peut être inconnu. Conservez la clé et les données d'entrée ; récupérez le reçu avant de créer un autre client. |
| `401` ou `403` | Résolvez le problème d'accès lié à l'identifiant, aux autorisations ou aux droits avant de réessayer. |
| `404` | Confirmez l'activation d'OAuth, l'hôte régional et la propriété de la ressource. |

Consultez [erreurs](/fr/developers/v1/errors/overview) pour les ID de requête et les détails de reprise.
N'envoyez jamais de secret client ni de jeton d'accès avec une demande d'assistance.

## Inspecter et révoquer

Utilisez votre identifiant de gestion et la ressource de la plateforme `id` :

| Opération | Requête | Succès |
| - | - | - |
| Inspecter l'état actuel | `GET /v1/oauth_clients/{id}` | `200`, ressource client sans secret |
| Révoquer l'accès | `DELETE /v1/oauth_clients/{id}` | `200`, ressource client révoquée sans secret |

La révocation bloque les requêtes d'API ultérieures du client, y compris celles effectuées avec des
jetons déjà émis. Elle n'annule pas le travail déjà accepté par l'API.
Le nettoyage distant des identifiants peut se terminer ultérieurement. Répéter la révocation est sans risque
et ne nécessite aucune clé de nouvelle tentative. Continuez à utiliser l'identifiant de gestion si le client
révoqué est lui-même un appelant de l'API.

## Renouveler sans perdre l'accès

Créez un second client avec le plafond de portées requis. Enregistrez son secret, obtenez un
jeton à l'aide de votre point de terminaison de jeton régional et vérifiez que l'intégration fonctionne
avec ce client. Basculez l'intégration vers le remplaçant, puis révoquez l'ancienne ressource.
Conservez un identifiant de gestion indépendant afin de pouvoir vous rétablir en cas de mauvais déploiement.

Les jetons d'accès ne peuvent pas accorder plus que les portées du client et les autorisations
actuelles du compte de service. Le retrait d'autorisations du compte ou la révocation d'un client prévaut
sur la durée de vie restante d'un jeton. Ne considérez pas un jeton mis en cache comme la preuve que
l'autorisation est toujours valide. Obtenez un nouveau jeton d'accès avant son expiration en
authentifiant de nouveau le client ; cet octroi n'utilise pas de jetons d'actualisation.


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