> ## Documentation Index > Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt > Use this file to discover all available pages before exploring further. # Authentification > Comprendre les principals, les jetons et comment s'authentifier avec l'API Devin 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
| 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é | Tous les identifiants API utilisent le format de préfixe `cog_`. Incluez votre token dans l’en-tête `Authorization` de chaque requête : ```bash theme={null} 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 ```bash theme={null} 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`
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](/fr/api-reference/getting-started/teams-quickstart) ou le [guide de démarrage rapide Enterprise](/fr/api-reference/getting-started/enterprise-quickstart). ***
## 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](mailto:support@cognition.ai) 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](/fr/api-reference/personal-access-tokens). ***
## Authentification héritée (obsolète)
Les anciennes API keys sont obsolètes. Utilisez [API v3](/fr/api-reference/v3/overview) avec l’authentification par utilisateur de service. Consultez le [guide de migration](/fr/api-reference/getting-started/migration-guide). 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é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 | **Où les générer :** [Settings > API Keys](https://app.devin.ai/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](/fr/work-with-devin/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
* [Guide de démarrage rapide Teams](/fr/api-reference/getting-started/teams-quickstart) — prise en main en quelques minutes * [Guide de démarrage rapide Enterprise](/fr/api-reference/getting-started/enterprise-quickstart) — configuration du RBAC et de plusieurs organisations * [Flux courants](/fr/api-reference/common-flows) — exemples de workflow de bout en bout * [Guide de migration](/fr/api-reference/getting-started/migration-guide) — migrer depuis les versions v1/v2