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.
| Principal | Token | Description |
|---|
| Utilisateur de service (non humain) | Service User API Key | Pour 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é |
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"
- 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.
Utilisateurs de service (recommandés pour l’automatisation)
- Créez un utilisateur de service dans Settings > Service users (organisation) ou Enterprise settings > Service users (enterprise)
- Attribuez un rôle qui contrôle les endpoints auxquels l’utilisateur de service peut accéder
- 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
- 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ètre | Créé dans | Accès API | Cas d’utilisation |
|---|
| Organization | Settings > Service users | /v3/organizations/* | Gestion des sessions, knowledge, playbooks, secrets |
| Enterprise | Enterprise 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
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.
- 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.
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. | Type de clé | Préfixe | Utilisé avec | Description |
|---|
| Clé d’API personnelle | apk_user_ | v1, v2 | Liée à un compte utilisateur, hérite des autorisations de l’utilisateur |
| Clé d’API de service | apk_ | v1 | Avec un périmètre organisationnel, pour l’automatisation |
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.
- Stockez les clés de manière sécurisée : utilisez des variables d’environnement ou des systèmes de gestion de secrets
- Renouvelez régulièrement les clés : générez de nouvelles clés et révoquez périodiquement les anciennes
- Utilisez des comptes de service pour l’automatisation : préférez les comptes de service aux clés personnelles en production
- Appliquez le principe du moindre privilège : accordez uniquement les autorisations minimales nécessaires
- Surveillez l’utilisation : examinez les journaux d’audit pour détecter toute activité API inattendue
- Révoquez immédiatement les clés compromises : si une clé est exposée, révoquez-la et générez-en une nouvelle
Causes possibles :
- API key invalide ou expirée
- En-tête
Authorization manquant
- Format du jeton Bearer incorrect
Solution : Vérifiez que votre API key est valide et correctement formatée dans l’en-tête Authorization.
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
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.
