Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.devin.ai/llms.txt

Use this file to discover all available pages before exploring further.

L’API Devin utilise un modèle principal + jeton. Un principal désigne qui vous êtes (votre identité), et un jeton est ce qui permet de le prouver (votre justificatif d’authentification). Comprendre cette distinction est essentiel pour choisir la méthode d’authentification adaptée à votre cas d’usage.

​
Principals & tokens

PrincipalTokenDescription
Utilisateur de service (non humain)Service User API KeyPour les intégrations automatisées et les pipelines CI/CD
Utilisateur (humain)Personal Access Token (PAT)Pour un accès programmatique humain sous votre propre identité
Tous les identifiants API utilisent le format de préfixe cog_. Incluez votre token dans l’en-tête Authorization de chaque requête : 
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer cog_your_token_here"
La distinction essentielle est le principal en tant que lequel le token s’authentifie :
  • Une Service User API Key s’authentifie en tant qu’utilisateur de service — l’identité, les autorisations et les appartenances aux orgs de l’utilisateur de service s’appliquent.
  • Un Personal Access Token s’authentifie en tant qu’utilisateur humain qui l’a créé — l’identité, les autorisations et les appartenances aux orgs de cet utilisateur s’appliquent.
Les utilisateurs de service sont des comptes non humains conçus pour les intégrations d’API. Des autorisations spécifiques peuvent leur être attribuées via RBAC, et ils peuvent être ajoutés à des organisations indépendamment des utilisateurs humains.

​
Fonctionnement

  1. Créez un utilisateur de service dans Settings > Service users (organisation) ou Enterprise settings > Service users (enterprise)
  2. Attribuez un rôle qui contrôle les endpoints auxquels l’utilisateur de service peut accéder
  3. Générez une API key — la clé commence par cog_ et n’est affichée qu’une seule fois lors de sa création
  4. Utilisez la clé dans l’en-tête Authorization de chaque requête API
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a simple Python script"}'

​
Périmètres des utilisateurs de service

PérimètreCréé dansAccès APICas d’utilisation
OrganizationSettings > Service users/v3/organizations/*Gestion des sessions, knowledge, playbooks, secrets
EnterpriseEnterprise settings > Service users/v3/enterprise/* + /v3/organizations/*Gestion inter-organisations, analyses, journaux d’audit, facturation
Trouvez l’ID de votre organisation sur la page Settings > Service Users.

​
Attribution des sessions avec create_as_user_id

Les utilisateurs de service sont des identités distinctes des utilisateurs humains. Par défaut, les sessions créées par un utilisateur de service sont attribuées à cet utilisateur de service lui-même. Pour créer des sessions au nom d’un utilisateur spécifique, passez le paramètre create_as_user_id lors de la création d’une session. La session apparaîtra dans la liste des sessions de cet utilisateur et sera prise en compte dans son utilisation. Cela nécessite l’autorisation ImpersonateOrgSessions sur le rôle de l’utilisateur de service.

​
Principales propriétés

  • Les clés commencent par cog_ et ne sont affichées qu’une seule fois lors de leur création
  • Les utilisateurs de service apparaissent séparément des utilisateurs humains dans les journaux d’audit
  • Les autorisations sont contrôlées via le RBAC — n’attribuez que ce dont l’intégration a besoin
  • Les utilisateurs de service Enterprise héritent des autorisations au niveau de l’org, dans toutes les organisations
Pour des instructions détaillées de configuration, consultez le guide de démarrage rapide Teams ou le guide de démarrage rapide Enterprise.

​
Jetons d’accès personnels (bêta fermée)

Les Personal Access Tokens sont actuellement en bêta fermée et soumis à un feature flag. Contactez le support pour y accéder. Les PAT ne sont pas disponibles pour les comptes SSO/Enterprise.
Les jetons d’accès personnels (PAT) permettent aux utilisateurs humains de s’authentifier de manière programmatique avec leur propre identité. Lorsque vous utilisez un PAT, l’API vous voit tel que vous — avec vos autorisations, vos appartenances à des orgs et votre journal d’audit. C’est utile lorsque vous souhaitez effectuer des appels d’API en votre nom (par exemple, pour des scripts personnels ou des outils locaux) plutôt que via un utilisateur de service partagé. Pour plus de détails, consultez Jetons d’accès personnels.

​
Authentification héritée (obsolète)

Les anciennes API keys sont obsolètes. Utilisez API v3 avec l’authentification par utilisateur de service. Consultez le guide de migration.
Les anciennes API keys sont utilisées avec les API v1 et v2. Elles continuent de fonctionner pendant la période de dépréciation, mais ne prennent pas en charge les nouvelles fonctionnalités comme le RBAC, l’attribution de session ou la pagination basée sur un curseur.
Type de cléPréfixeUtilisé avecDescription
Clé d’API personnelleapk_user_v1, v2Liée à un compte utilisateur, hérite des autorisations de l’utilisateur
Clé d’API de serviceapk_v1Avec un périmètre organisationnel, pour l’automatisation
Où les générer : Settings > API Keys

​
Bonnes pratiques de sécurité

Ne partagez jamais d’API keys dans des espaces accessibles publiquement, comme les dépôts GitHub, le code côté client ou les journaux.
  1. Stockez les clés de manière sécurisée : utilisez des variables d’environnement ou des systèmes de gestion de secrets
  2. Renouvelez régulièrement les clés : générez de nouvelles clés et révoquez périodiquement les anciennes
  3. Utilisez des comptes de service pour l’automatisation : préférez les comptes de service aux clés personnelles en production
  4. Appliquez le principe du moindre privilège : accordez uniquement les autorisations minimales nécessaires
  5. Surveillez l’utilisation : examinez les journaux d’audit pour détecter toute activité API inattendue
  6. Révoquez immédiatement les clés compromises : si une clé est exposée, révoquez-la et générez-en une nouvelle

​
Dépannage

​
401 Non autorisé

Causes possibles :
  • clé API invalide ou expirée
  • En-tête Authorization manquant
  • Format du jeton Bearer incorrect
  • Utilisation d’une ancienne clé API (apk_ / apk_user_) avec Devin MCP — seules les clés préfixées par cog_ sont prises en charge
Solution : Vérifiez que votre clé API est valide et correctement formatée dans l’en-tête Authorization. Pour l’utilisation de MCP, assurez-vous d’utiliser une clé API d’utilisateur de service (et non une ancienne clé).

​
403 Interdit

Causes possibles :
  • L’API key ne dispose pas des autorisations requises
  • Utilisation d’un type de clé inadapté pour l’endpoint (par ex. clé legacy avec des endpoints v3)
  • Tentative d’accès à des ressources en dehors de votre périmètre d’autorisation
Solution :
  • Assurez-vous que votre utilisateur de service dispose des rôles et autorisations appropriés
  • Pour les endpoints legacy v2 : assurez-vous de disposer du rôle d’administrateur Enterprise
  • Pour les endpoints legacy v1 : vérifiez que vous avez bien accès à l’organisation

​
404 Introuvable

Causes possibles :
  • URL de l’endpoint de l’API incorrecte
  • La ressource n’existe pas ou vous n’y avez pas accès
Solution : Vérifiez l’URL de l’endpoint et que la ressource existe bien.

​
Prochaines étapes