Skip to main content
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 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, contactez l’assistance de Living Security.
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 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 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 :
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 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. Consultez erreurs 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 : 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.