Authentication

L'API GitGuardian utilise des clés d'API pour authentifier les requêtes.

Créer votre clé d'API

Il existe 2 types de clés d'API différents :

• Comptes de service : un type spécial de token destiné à représenter un utilisateur non humain qui doit s'authentifier et être autorisé pour des scénarios tels que le scan de secrets dans des pipelines CI ou le traitement par lots d'incidents ouverts.
• Personal access tokens : un token destiné à l'utilisation de l'API GitGuardian et de l'application en ligne de commande ggshield par les développeurs individuels sur leurs postes de travail locaux (par exemple, des hooks git pre-commit ou pre-push).

Vous devez créer un compte afin d'obtenir une clé d'API. Votre clé d'API doit rester privée et ne doit ni être intégrée directement dans le code ni versionnée dans Git. (Merci de ne pas pousser les clés d'API GitGuardian vers des dépôts publics GitHub ^^).

Comme dans l'exemple ci-dessous, utilisez le endpoint /health pour vérifier la validité de votre clé d'API.

Schéma d'authentification

L'API GitGuardian utilise l'authentification par en-tête Authorization pour ses requêtes. La valeur de l'en-tête Authorization doit être préfixée par Token.

Exemple de requête avec curl :

curl -H "Authorization: Token ${TOKEN}" \
  https://api.gitguardian.com/v1/health

Scopes

Les scopes sont liés à une clé d'API et contrôlent l'accès aux ressources ainsi que la capacité de scan.

Scopes de gestion des données du Dashboard

• incidents

  • incidents:share : accorde les permissions de visualisation, d'édition et de partage sur les incidents de votre workspace GitGuardian.
  • incidents:write : accorde les permissions de visualisation et d'édition sur les incidents de votre workspace GitGuardian.
  • incidents:read : accorde la permission de visualisation seule sur les incidents de votre workspace GitGuardian.

• sources

  • sources:write : accorde les permissions de visualisation et d'édition sur les sources (dépôts de code uniquement) de votre workspace GitGuardian.
  • sources:read : accorde la permission de visualisation seule sur les sources (dépôts de code uniquement) de votre workspace GitGuardian.

• honeytokens

  • honeytokens:write : accorde les permissions de visualisation et d'édition sur les honeytokens de votre workspace GitGuardian. Disponible sous conditions spécifiques : le produit honeytoken doit être activé pour le workspace, et pour les personal access tokens le rôle doit être au minimum « manager ».
  • honeytokens:read : accorde la permission de visualisation seule sur les honeytokens de votre workspace GitGuardian. Disponible sous conditions spécifiques : le produit honeytoken doit être activé pour le workspace, et pour les personal access tokens le rôle doit être au minimum « manager ».
  • honeytokens:check : accorde la permission de vérifier si un secret détecté est un honeytoken, sans exposer les détails du honeytoken. Utilisé par ggshield pendant les scans afin que les honeytokens soient reconnus au lieu d'être traités comme des secrets actifs ou déclenchés accidentellement. Contrairement aux scopes read/write des honeytokens, il ne nécessite pas de rôle Manager.

• members

  • members:write : accorde les permissions de visualisation et d'édition sur les membres de votre workspace GitGuardian.
  • members:read : accorde la permission de visualisation sur les membres de votre workspace GitGuardian.

• teams

  • teams:write : accorde les permissions de visualisation et d'édition sur les équipes de votre workspace GitGuardian.
  • teams:read : accorde la permission de visualisation sur les équipes de votre workspace GitGuardian.

• api_tokens

  • api_tokens:write : accorde les permissions de visualisation et d'édition sur les tokens d'API (personal access tokens et comptes de service) de votre workspace GitGuardian.
  • api_tokens:read : accorde la permission de visualisation sur les tokens d'API (personal access tokens et comptes de service) de votre workspace GitGuardian.

• audit_logs:read : accorde la permission de visualisation sur les journaux d'audit de votre workspace GitGuardian. Si vous utilisez des personal access tokens, cela n'est disponible que pour les Managers.

• ip_allowlist

  • ip_allowlist:write : accorde les permissions de visualisation et d'édition sur la liste d'autorisation d'IP de votre workspace GitGuardian.
  • ip_allowlist:read : accorde la permission de visualisation seule sur la liste d'autorisation d'IP de votre workspace GitGuardian.

• custom_tags

  • custom_tags:write : accorde les permissions de visualisation et d'édition sur les tags personnalisés de votre workspace GitGuardian.
  • custom_tags:read : accorde la permission de visualisation seule sur les tags personnalisés de votre workspace GitGuardian.

• secrets

  • secrets:write : accorde les permissions de visualisation et d'édition sur les secrets NHI de votre workspace GitGuardian.
  • secrets:read : accorde la permission de visualisation seule sur les secrets NHI de votre workspace GitGuardian.

• nhi

  • nhi:send-inventory : accorde la permission d'envoyer les données d'inventaire NHI à GitGuardian.
  • nhi:write-vault : accorde la permission de recevoir des instructions d'écriture de GitGuardian pour la synchronisation des secrets.
  • nhi:ownership:write : accorde les permissions de visualisation et d'édition sur la propriété NHI.
  • nhi:ownership:read : accorde la permission de visualisation seule sur la propriété NHI.

• public-perimeter:read : accorde la permission de visualisation sur le périmètre de public monitoring de votre workspace GitGuardian.

• endpoints:send : accorde la permission de téléverser les résultats de scan Endpoint Protection, les métadonnées machine et les découvertes vers votre workspace GitGuardian. Utilisé par ggshield machine submit et ggshield machine report. La détection s'exécute sur l'endpoint, donc ce scope n'accorde pas le scan.

• ai-discover:send : accorde la permission de téléverser l'inventaire des agents IA et des serveurs MCP trouvés sur un endpoint. Utilisé par ggshield ai discover. Disponible avec les plans Business et Enterprise.

Scope de capacité de scan

• scan : accorde les permissions de scanner tout contenu textuel à la recherche de secrets avec le moteur de détection de secrets GitGuardian. Requis pour utiliser ggshield.
• scan:create-incidents : accorde les permissions de scanner du contenu et de créer des incidents à partir de sources personnalisées. Inclut le scope scan.

Vous pouvez même tester cette capacité directement dans la section Secrets detection playground de votre dashboard :