Skip to main content
Utilisez les identifiants client OAuth lorsque votre intégration backend a besoin de jetons d’accès à courte durée de vie 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 limitée suffit pour une intégration serveur privée capable de stocker et de renouveler une clé de façon sécurisée. Consultez Authentification pour choisir entre les deux méthodes et comprendre comment s’intègrent les comptes de service.
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, communiquez avec le soutien de Living Security.
L’octroi d’identifiants client représente votre compte de service. Il n’authentifie aucune personne et ne demande à aucun client d’autoriser une application. L’autorisation déléguée au moyen d’un navigateur est une fonctionnalité OAuth distincte et n’est pas offerte par ces opérations.

Avant de commencer

  • Créez un compte de service disposant uniquement des autorisations dont l’intégration a besoin.
  • Utilisez un identifiant de gestion avec service_account:manage et chaque autorisation que vous souhaitez accorder au nouveau client. Le compte cible doit également détenir ces autorisations. Un client ne peut étendre les pouvoirs d’aucun des deux comptes.
  • Choisissez la région de l’organisation. Les identifiants d’API et les jetons d’accès OAuth doivent être utilisés avec l’hôte d’API régional correspondant.
  • Conservez le secret du client et les jetons dans votre espace de stockage de secrets côté serveur. Ne les placez jamais dans le code d’un navigateur, dans des applications mobiles, dans le contrôle de code source ni dans les journaux de requêtes.

Créer un client

POST /v1/oauth_clients exige 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 combinée maximale de 4 096 caractères. Chaque compte de service peut avoir au plus 20 clients ou opérations de création ou de 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 est avéré avant le début du travail du fournisseur peut libérer son emplacement en toute sécurité. Sa clé de nouvelle tentative appartient toujours à la tentative d’origine; récupérez ce reçu avant de décider de créer un remplacement. Choisissez une clé de nouvelle tentative pour cette tentative de création et conservez-la 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 perte de réponse. Le renouvellement de l’identifiant de gestion sous le même compte de service ne crée pas une nouvelle identité de nouvelle tentative. Installez le paquet requests de Python. Chargez les valeurs d’environnement suivantes au moyen de votre gestion habituelle des secrets et de la configuration :
Python
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 plutôt que de créer silencieusement un autre client. Les exceptions réseau exigent aussi 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 être null pendant que la création est en attente.
  • client_secret est renvoyé uniquement à la requête qui termine la création. Chaque requête de création répétée renvoie null, y compris une nouvelle tentative après une réponse de réussite 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. Consultez erreurs pour les ID de requête et les détails de reprise. N’envoyez jamais un secret de client ni un jeton d’accès avec une demande de soutien.

Consulter et révoquer

Utilisez votre identifiant de gestion et la ressource de la plateforme id : La révocation bloque les requêtes d’API subséquentes du client, y compris celles qui utilisent des jetons déjà émis. Elle n’annule pas le travail déjà accepté par l’API. Le nettoyage à distance des identifiants peut se terminer plus tard. Il est sûr de répéter la révocation, qui n’exige aucune clé de nouvelle tentative. Continuez à utiliser l’identifiant de gestion si le client en cours de révocation est lui-même un appelant de l’API.

Effectuer une rotation sans perdre l’accès

Créez un second client avec le plafond de portées requis. Enregistrez son secret, obtenez un jeton au moyen du point de terminaison de jeton de votre région et vérifiez que l’intégration fonctionne avec ce client. Basculez l’intégration vers le remplacement, puis révoquez l’ancienne ressource. Conservez un identifiant de gestion indépendant afin de pouvoir reprendre après un déploiement défaillant. Les jetons d’accès ne peuvent pas accorder plus que les portées du client et les autorisations actuelles du compte de service. La suppression d’autorisations du compte ou la révocation d’un client a préséance sur la durée de vie restante d’un jeton. Ne considérez pas un jeton mis en cache comme une preuve que l’autorisation est toujours valide. Obtenez un nouveau jeton d’accès avant l’expiration en authentifiant de nouveau le client; cet octroi n’utilise pas de jetons d’actualisation.