Présentation

Les jetons d’accès personnels (PATs) sont un type d’identifiant qui authentifie les appels de Datadog API. Contrairement aux clés d’application, les PAT n’ont pas besoin d’être associés à une clé d’API. Ils sont à durée de vie limitée et à portée définie par défaut, ce qui vous donne un contrôle plus strict sur ce à quoi chaque jeton peut accéder et sur sa durée de validité.

Avec les PATs, vous pouvez :

• Authentifier les appels d’API avec un identifiant unique.
• Appliquez le principe du moindre privilège en sélectionnant uniquement les portées dont votre workflow a besoin.
• Limitez l’impact d’une fuite d’identifiants grâce à des valeurs de durée de vie (TTL) obligatoires. Les jetons expirés sont automatiquement révoqués, de sorte que les identifiants inactifs ne persistent pas indéfiniment.
• Séparez les préoccupations en réservant les clés d’API à la soumission de télémétrie (Agent, logs, métriques) et utilisez les PAT pour tous les autres appels d’API web.

Comparaison des PAT avec d’autres types d’identifiants

Pour les jetons d’accès de service, consultez Service Access Tokens.

Prérequis

• Un compte utilisateur Datadog avec l’autorisation user_app_keys
• L’autorisation org_app_keys_write si vous souhaitez gérer les PATs pour d’autres utilisateurs de l’organisation

Créer un jeton d’accès personnel

1. Accédez à Paramètres personnels > Jetons d’accès.
2. Cliquez sur
   • New Access Token
   .
3. Saisissez un Name pour le jeton.
4. Sélectionnez une Expiration Date. La durée d’expiration minimale est de 24 heures et la durée maximale est d’un an à compter de la création.
5. Cliquez sur Select Scopes pour choisir les portées qui définissent ce à quoi ce jeton peut accéder. Au moins un périmètre est requis. Accordez uniquement les autorisations requises par votre workflow, puis cliquez sur Save.

Utilisez un jeton d’accès personnel

Les PATs prennent en charge deux méthodes d’authentification.

En-tête d’autorisation (recommandé)

Transmettez le PAT en tant que jeton Bearer dans l’en-tête Authorization. Cette méthode ne nécessite pas de clé d’API :

curl -X GET "https://api.datadoghq.com/api/v2/users" \
  -H "Authorization: Bearer <YOUR_PAT>"

En-tête de clé d’application

Transmettez le PAT dans l’en-tête dd-application-key. Ceci est utile pour migrer des intégrations existantes qui utilisent déjà le format d’en-tête de clé d’application :

curl -X GET "https://api.datadoghq.com/api/v2/users" \
  -H "dd-application-key: <YOUR_PAT>"

Remarque : Lorsqu’un PAT valide est fourni dans l’en-tête dd-application-key, Datadog s’authentifie uniquement avec le PAT. L’en-tête dd-api-key est facultatif et sa valeur n’est pas évaluée.

Restrictions sur les appels d’API authentifiés par PAT

Pour empêcher l’élévation de privilèges, Datadog restreint ce qu’un appel d’API authentifié avec un PAT peut faire. Ces restrictions s’appliquent quel que soit le client API effectuant l’appel :

• Clés d’application : un PAT ne peut pas créer ou mettre à jour des clés d’application. La révocation des clés d’application est autorisée.
• Portées sur les nouveaux jetons : un PAT ne peut créer ou mettre à jour un PAT ou un SAT que si les portées du nouveau jeton sont un sous-ensemble de ses propres portées.
• Durée de vie (TTL) sur les nouveaux jetons : un PAT ne peut pas créer un PAT ou un SAT avec une durée de vie qui dépasse sa propre expiration.

Un appel qui enfreint l’une de ces restrictions renvoie une réponse 403 Forbidden.

Gérer les jetons d’accès personnels

Voir vos jetons

Accédez à Paramètres personnels > Jetons d’accès pour voir tous les PATs associés à votre compte, y compris leurs noms, portées, dates d’expiration et informations sur la dernière utilisation.

Après la création d’un jeton, un panneau de détails affiche le secret du jeton, son nom, l’ID du jeton, le propriétaire, les portées et la date d’expiration. Depuis ce panneau, vous pouvez également modifier ou révoquer le jeton.

Gérer les jetons en tant qu’administrateur

Les administrateurs d’organisation disposant des autorisations org_app_keys_read et org_app_keys_write peuvent afficher et gérer les PATs pour tous les utilisateurs de l’organisation à partir de Paramètres de l’organisation > Jetons d’accès.

Révoquer un jeton

1. Accédez à Paramètres personnels > Jetons d’accès, ou Paramètres de l’organisation > Jetons d’accès pour les administrateurs.
2. Passez la souris sur le jeton que vous souhaitez révoquer et cliquez sur l’icône Revoke Token.

Les jetons révoqués ne peuvent plus authentifier les appels d’API. La révocation prend effet en quelques secondes.

Modifier un jeton

Vous pouvez mettre à jour le nom et les portées d’un PAT existant. Vous ne pouvez pas modifier la durée de vie (TTL) après la création. Pour modifier la durée de vie, révoquez le jeton existant et créez un jeton avec la configuration souhaitée.

Format du jeton

Les PATs utilisent un format identifiable qui prend en charge l’analyse des secrets et la gestion des clés :

ddpat_<ALIAS>_<SECRET><CHECKSUM>

Le préfixe identifiable et la somme de contrôle permettent une détection automatisée par les services d’analyse des secrets, notamment l’analyse des secrets GitHub, Sensitive Data Scanner et GitGuardian.

Autorisations

Les PATs utilisent les mêmes autorisations que les clés d’application :

Pour plus d’informations sur les autorisations, consultez Access Control basé sur les rôles.

Audit Trail

Si la Audit Trail est activée pour votre organisation, la Audit Trail enregistre tous les événements de création, d’utilisation et de révocation de PATs. La Audit Trail capture la méthode d’authentification et les métadonnées du jeton pour chaque appel API effectué avec un PAT, offrant aux administrateurs une visibilité sur l’utilisation des identifiants dans toute l’organisation.

Pour examiner l’activité des PAT, accédez à Security > Compliance > Audit Trail et filtrez par la méthode d’authentification Personal Access Token.

Référence de l’API

Gérez les PATs par programmation via la Datadog API :

L’endpoint GET /api/v2/personal_access_tokens renvoie à la fois les PAT et les SAT en un seul appel. Pour gérer les Jetons d’accès de service (SATs), consultez Jetons d’accès de service.

Pour la référence complète de l’API, consultez Gestion des clés.

Délai de propagation de la clé

Les PAT suivent un modèle de cohérence éventuelle. Après la création ou la révocation, les modifications peuvent prendre quelques secondes pour se propager dans tous les systèmes Datadog. N’utilisez pas un jeton immédiatement après sa création dans des workflows critiques. Mettez en œuvre une stratégie de réessai avec un court délai d’attente exponentiel pour gérer les erreurs transitoires pendant la fenêtre de propagation.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Modernisez l’authentification à la Datadog API avec des identifiants à portée définie.BLOG