Clés API

Les clés API authentifient vos demandes auprès de l'API DiffHook et identifient les ressources de l'équipe auxquelles vous accédez.

Création d'une clé

1. Accédez à Application → Paramètres → Clés API
2. Cliquez sur Nouvelle clé API
3. Donnez-lui une étiquette descriptive (par exemple production-server, ci-pipeline)
4. Copiez immédiatement l'ID client et le Secret client : ils ne s'affichent qu'une seule fois.

Le Client ID est votre identifiant public : il commence par dh_live_. Après la création, Paramètres répertorie chaque clé par étiquette et ID client complet afin que vous puissiez copier l'ID à tout moment ; le secret n'est plus jamais montré.

Si vous oubliez de copier le secret, supprimez la clé et créez-en une nouvelle.

Autorisations clés

Toutes les clés ont actuellement un accès complet aux ressources de votre équipe (moniteurs, journaux, paramètres). Les clés par portée (lecture seule, journaux uniquement, etc.) se trouvent sur la feuille de route.

Si vous devez restreindre l'accès aujourd'hui, créez une équipe distincte pour les intégrations en lecture seule et invitez-y des membres limités.

Secrets de signature

Votre secret de signature est distinct de votre clé API. Il est utilisé exclusivement pour signer les charges utiles des webhooks sortants afin que votre serveur puisse vérifier qu'elles proviennent de DiffHook.

Trouvez-le dans Application → Paramètres → Clés API → Secret de signature.

Voir Vérifier les signatures pour savoir comment l'utiliser.

Rotation d'une clé

1. Créez une nouvelle clé et mettez à jour vos applications pour l'utiliser
2. Vérifiez que la nouvelle clé fonctionne en production
3. Supprimez l'ancienne clé de Application → Paramètres → Clés API

Il n’existe pas de raccourci de rotation de clé qui remplace automatiquement une clé en place – suivez toujours le flux créer → migrer → supprimer pour éviter les temps d’arrêt.

Rotation de votre secret de signature

Accédez à Application → Paramètres → Clés API → Rotation du secret de signature.

Après rotation :

• Tous les futurs webhooks sont immédiatement signés avec le nouveau secret
• Les livraisons en vol peuvent toujours porter l'ancienne signature
• Mettez à jour le secret de votre serveur avant de révoquer l'ancien

Révoquer une clé

Supprimez la clé de Application → Paramètres → Clés API. La révocation est instantanée : la clé ne peut plus être utilisée pour demander de nouveaux jetons.

Cependant, les jetons au porteur déjà émis avec cette clé restent valables jusqu'à leur expiration naturelle (jusqu'à 24 heures après leur génération).

Meilleures pratiques clés en matière de sécurité

• Ne validez jamais les clés dans le contrôle de source. Utilisez des variables d'environnement ou un gestionnaire de secrets (par exemple AWS Secrets Manager, Doppler, Vault).
• Utilisez une clé par environnement. Conservez des clés distinctes pour le développement, la préparation et la production afin de pouvoir en révoquer une sans affecter les autres.
• Faites pivoter les clés périodiquement. Traitez toute clé datant de plus de 90 jours comme candidate à la rotation.
• Surveillez les fuites. Si une clé apparaît dans un référentiel ou un journal public, révoquez-la immédiatement et créez-en une nouvelle.

Dépannage des erreurs d'authentification

401 Unauthorized

• Les informations d'identification sont manquantes, mal formées ou la clé a été révoquée
• Pour les clés API : utilisez un JWT de POST /api/oauth/token

403 Forbidden

• La clé est valide mais n'a pas accès à la ressource demandée (par exemple un moniteur appartenant à une autre équipe)