Skip to main content

​
Vue d’ensemble

Les jetons d’accès personnels (PAT) permettent aux utilisateurs humains de s’authentifier de manière programmatique sous leur propre identité. Contrairement aux API key d’utilisateur de service (qui s’authentifient comme un utilisateur de service non humain), un PAT s’authentifie comme vous — l’utilisateur humain qui a créé le jeton. Tous les identifiants API utilisent le format de préfixe cog_. Les deux types de jeton s’utilisent de manière identique dans l’en-tête Authorization :

​
Portée et autorisations

Un PAT vous appartient, au sein de votre compte (votre compte Teams ou votre entreprise). Il n’est rattaché à aucune organisation en particulier, et il n’existe pas de « PAT d’organisation » ni de « PAT d’entreprise ». Cela diffère des utilisateurs de service, qui sont créés au niveau de l’organisation ou de l’entreprise. Chaque requête sélectionne l’organisation. Les endpoints d’organisation l’indiquent dans le chemin d’URL (/v3/organizations/{org_id}/...), et la requête est autorisée en fonction de votre accès et de votre rôle dans cette organisation. Une requête visant une organisation à laquelle vous n’avez pas accès échoue. Le jeton dispose des mêmes autorisations que votre utilisateur. Tout ce que vous pouvez faire dans l’application web, vous pouvez le faire avec votre PAT, et rien de plus. Pour créer, renouveler ou révoquer des PAT, vous devez disposer de l’autorisation Gérer les clés API dans l’organisation dont vous consultez les paramètres, ou de l’autorisation Gérer les clés API du compte au niveau du compte. Cette autorisation détermine qui peut gérer les jetons ; elle ne modifie pas ce qu’un jeton peut faire. Les comptes Enterprise disposent également d’une organisation interne qui stocke uniquement les paramètres à l’échelle de l’entreprise. Ce n’est pas un espace de travail. Les requêtes PAT qui la ciblent sont rejetées avec 403 ; utilisez donc toujours l’ID d’une organisation enfant.

​
Quand utiliser les PAT

Les PAT sont conçus pour les cas où vous avez besoin d’un accès programmatique à l’API en votre nom propre :
  • Scripts et outils personnels — automatisez vos propres workflows sans utilisateur de service partagé
  • Développement local — testez des intégrations d’API avec votre propre compte
  • Automatisation de courte durée — scripts ponctuels qui doivent vous être attribués
Pour les intégrations en production, les pipelines CI/CD et l’automatisation partagée, utilisez plutôt les API keys d’utilisateur de service. Les utilisateurs de service offrent une meilleure traçabilité d’audit, une gestion centralisée des clés et des contrôles RBAC. Si vous ne savez pas lequel utiliser, consultez la comparaison.

​
Création et gestion des PAT

Gérez vos PAT dans l’onglet PATs de la page Devin API des Settings, dans n’importe quelle organisation ou dans les settings Enterprise. L’onglet affiche les mêmes jetons dans les deux cas (voir Périmètre et autorisations).
  1. Créez un PAT — attribuez-lui un nom et une date d’expiration. Le jeton commence par cog_ et n’est affiché qu’une seule fois, lors de sa création.
  2. Utilisez le jeton dans l’en-tête Authorization — exactement comme une API key d’utilisateur de service. Chaque appel d’API s’authentifie avec votre compte utilisateur : vos autorisations, vos appartenances à des org et votre piste d’audit s’appliquent.
  3. Effectuez la rotation d’un PAT — générez un nouveau secret pour un jeton existant sans modifier son nom ; l’ancien secret cesse immédiatement de fonctionner.
  4. Révoquez un PAT — invalidez le jeton à tout moment.
Les PAT sont également acceptés par les endpoints en temps réel, tels que le WebSocket ACP live, afin que des outils comme Devin CLI et les clients de bureau puissent s’authentifier avec un PAT.

​
Gouvernance Enterprise

Pour les comptes Enterprise, la disponibilité des PAT est régie par une politique de PAT à l’échelle de l’entreprise, qui s’applique à toutes les organisations de l’entreprise. Les administrateurs Enterprise disposant de l’autorisation Gérer les paramètres Enterprise configurent cette politique (et traitent les demandes d’approbation) dans l’onglet Politiques de PAT de la page Settings Enterprise Devin API.

​
Modes de politique

​
Politique d’expiration

Lorsque les PAT sont activés pour une entreprise, chaque PAT doit avoir une date d’expiration, dont la durée de validité est limitée par la durée maximale définie par la politique (365 jours par défaut ; les administrateurs peuvent définir une limite plus courte). Les comptes non Enterprise (Teams) peuvent créer des PAT sans date d’expiration.

​
Workflow d’approbation

Avec l’option Approbation requise :
  1. Un membre demande un PAT depuis l’onglet PATs (nom et date d’expiration).
  2. Les administrateurs Enterprise voient la demande dans la file d’approbation et l’approuvent ou la refusent.
  3. Une fois la demande approuvée, le membre la finalise pour générer le jeton (affiché une seule fois).
  4. Les demandes en attente expirent automatiquement après 7 jours si aucune action n’est entreprise.
Les demandeurs et les administrateurs sont avertis par e-mail à chaque étape du cycle de vie du jeton (demandé, approuvé, refusé, révoqué).

​
Inventaire et révocation des tokens

Les Enterprise Admin disposant de l’autorisation Gérer les clés API du compte peuvent ouvrir la vue PAT inventory dans l’onglet Politiques de PAT pour :
  • Afficher les PAT de l’ensemble de l’Enterprise, avec pour chaque token son nom, son propriétaire, sa date de création, sa date d’expiration et son statut (Active, Revoked ou Expired). Vous pouvez filtrer par statut ou effectuer une recherche par nom ou par propriétaire.
  • Révoquer un token actif directement depuis sa ligne. L’inventaire ne permet de révoquer qu’un seul token à la fois.
L’inventaire n’indique pas si un token est conforme à la politique en vigueur. La conformité est vérifiée lorsque vous modifiez la politique : si un nouveau mode ou une durée d’expiration maximale plus courte rend des tokens existants non conformes, une boîte de dialogue de confirmation répertorie les tokens concernés et leurs violations avant que la modification ne soit appliquée. Les administrateurs qui ne disposent pas de l’autorisation Gérer les clés API du compte voient uniquement le nombre de tokens concernés. Une fois la modification confirmée, ces tokens sont révoqués et les demandes en attente de leurs propriétaires sont annulées. Le passage de la politique en mode désactivé révoque tous les PAT actifs et annule toutes les demandes en attente.

​
Révocation automatique

Les PAT d’un utilisateur sont automatiquement révoqués lorsqu’il n’est plus membre du compte, y compris en cas de déprovisionnement SCIM ou de modification des groupes de l’IdP.

​
Considérations de sécurité

  • Traitez les PAT avec le même soin que des mots de passe — ils donnent un accès complet à votre compte
  • Stockez les PAT dans des variables d’environnement ou des gestionnaires de secrets, jamais dans le code source
  • Définissez l’expiration la plus courte compatible avec votre cas d’usage
  • Révoquez immédiatement les PAT s’ils sont compromis
  • Privilégiez les API key d’utilisateur de service pour toute automatisation partagée ou en production

​
Prochaines étapes