GitGuardian Authentication: API Keys & Integrations (2026)

Authentication overview

GitGuardian provides a platform for detecting and remediating secrets across the software development lifecycle, from source code to infrastructure. Secure authentication is central to integrating GitGuardian into development workflows, enabling automated scanning, incident response, and custom tooling. The primary mechanism for programmatic access to the GitGuardian API, CLI, and various integrations is the use of API keys. These keys act as bearer tokens, granting access rights based on the permissions configured for them. For user-facing interactions with the GitGuardian dashboard, standard username/password authentication is employed, often supplemented by multi-factor authentication (MFA) for enhanced security.

Integrating GitGuardian typically involves authenticating components such as:

• GitGuardian API: For custom scripting, automation, and integrating with internal systems to retrieve scan results, manage incidents, or configure monitoring policies.
• GitGuardian CLI (ggshield): For local secrets scanning prior to committing code, often integrated into pre-commit hooks.
• Version Control System (VCS) integrations: Connecting GitGuardian to platforms like GitHub, GitLab, or Bitbucket for continuous monitoring of repositories. This often utilizes OAuth for initial setup and then GitGuardian's internal mechanisms for ongoing polling or webhook reception.
• CI/CD pipeline integrations: Embedding secrets scanning into continuous integration and continuous delivery pipelines to prevent secrets from being introduced into builds or deployments.

Understanding the appropriate authentication method for each use case is crucial for maintaining a secure and efficient secrets detection program. The GitGuardian documentation provides detailed guidance on authenticating with the GitGuardian platform across these different scenarios.

Supported authentication methods

GitGuardian supports several authentication methods, each designed for specific interaction types and security requirements. The choice of method depends on whether a human user is accessing the dashboard or an automated system is interacting with the API or CLI.

API Keys

API keys are the foundational method for programmatic access to the GitGuardian API and CLI. These keys are long, randomly generated strings that serve as unique identifiers and authentication credentials. When an API key is included in an HTTP request or used with the CLI, GitGuardian verifies its validity and the permissions associated with it to authorize the requested action. GitGuardian API keys are typically passed in the Authorization header as a Bearer token.

OAuth 2.0 (for VCS Integrations)

While API keys are used for direct API and CLI interactions, GitGuardian leverages OAuth 2.0 for integrating with Version Control Systems (VCS) like GitHub, GitLab, and Bitbucket. OAuth 2.0 provides a secure mechanism for GitGuardian to request delegated access to a user's VCS resources without requiring their credentials. This process typically involves a user authorizing GitGuardian through their VCS provider, which then issues an access token to GitGuardian. This token allows GitGuardian to access repositories, webhooks, and other necessary resources to perform secrets monitoring. The OAuth 2.0 specification is a widely adopted industry standard for delegated authorization.

User Login (Username/Password with MFA)

For human users accessing the GitGuardian dashboard to configure settings, review incidents, or manage teams, a traditional username and password authentication system is used. GitGuardian strongly recommends and supports multi-factor authentication (MFA) to add an extra layer of security to these user accounts. MFA typically involves a second verification step, such as a code from a mobile authenticator app (e.g., Google Authenticator, Authy) or a security key, reducing the risk of unauthorized access even if a password is compromised.

The following table summarizes the primary authentication methods:

Getting your credentials

To interact with the GitGuardian API or CLI, you will need to generate an API key. This process is managed directly within the GitGuardian dashboard.

Generating an API Key

1. Log in to the GitGuardian Dashboard: Access your GitGuardian account via the web interface at app.gitguardian.com.
2. Navigate to API Keys: In the dashboard, typically find the "API Keys" or "Settings" section. The exact path may vary slightly but is usually under a user or organization settings menu. Refer to the GitGuardian API Key management guide for the most up-to-date navigation.
3. Create a New API Key: Click on the option to create a new API key. You will typically be prompted to provide a descriptive name for the key (e.g., "CI/CD Pipeline Key," "Local CLI Access") to help identify its purpose later.
4. Configure Permissions (Scopes): GitGuardian allows you to define specific permissions (scopes) for each API key. This is a critical security practice known as the principle of least privilege. Assign only the minimum necessary permissions for the key's intended use. For example, a key used only for scanning might not need permissions to manage incidents.
5. Copy the API Key: Once generated, the API key will be displayed. It is crucial to copy this key immediately and store it securely, as it will typically only be shown once and cannot be retrieved later. If lost, you will need to generate a new key.

Integrating with VCS (OAuth 2.0 Setup)

For integrating GitGuardian with your Version Control System, the process is slightly different and involves an OAuth flow:

1. Navigate to Integrations: In the GitGuardian dashboard, go to the "Integrations" section.
2. Select your VCS Provider: Choose your VCS provider (e.g., GitHub, GitLab, Bitbucket).
3. Authorize GitGuardian: You will be redirected to your VCS provider's authorization page. Review the permissions GitGuardian requests and authorize the connection. This establishes the OAuth token exchange.
4. Configure Repositories: Once authorized, you can select which repositories GitGuardian should monitor within the dashboard.

Authenticated request example

Interacting with the GitGuardian API using an API key involves including the key in the Authorization header of your HTTP requests. The key should be prefixed with Bearer.

Here's an example using curl to list incidents, assuming you have an API key named YOUR_GITGUARDIAN_API_KEY:

curl -X GET \
  'https://api.gitguardian.com/v1/incidents' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_GITGUARDIAN_API_KEY'

In Python, using the requests library:

import requests

api_key = "YOUR_GITGUARDIAN_API_KEY"
headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {api_key}"
}

response = requests.get("https://api.gitguardian.com/v1/incidents", headers=headers)
response.raise_for_status() # Raise an exception for HTTP errors

print(response.json())

For the GitGuardian CLI (ggshield), you typically set the API key as an environment variable or pass it directly:

export GITGUARDIAN_API_KEY="YOUR_GITGUARDIAN_API_KEY"
ggshield scan path/to/your/code

Alternatively, you can configure it using the ggshield config set command:

ggshield config set api_key YOUR_GITGUARDIAN_API_KEY

More examples and detailed API endpoint information are available in the GitGuardian API Reference.

Security best practices

Securing your GitGuardian authentication credentials is paramount to protecting your secrets detection efforts and preventing unauthorized access to sensitive information. Adhering to these best practices helps mitigate common security risks:

• Principle of Least Privilege: When generating API keys, always assign the minimum necessary permissions (scopes) required for the key's intended function. Avoid granting broad administrative access to keys used for automated tasks. The GitGuardian documentation on API key scopes provides guidance on appropriate permissions.
• Secure Storage of API Keys: Never hardcode API keys directly into source code. Instead, use secure methods for storing and accessing them:
  • Environment Variables: For CI/CD pipelines and local development, environment variables are a common and effective method.
  • Secret Management Systems: For production environments, utilize dedicated secret management solutions like HashiCorp Vault, AWS Secrets Manager, Google Secret Manager, or Azure Key Vault.
  • Configuration Files: If using configuration files, ensure they are excluded from version control (e.g., via .gitignore) and have appropriate file system permissions.
• Key Rotation: Regularly rotate your API keys. This practice minimizes the window of opportunity for an attacker if a key is compromised. Establish a schedule for rotation based on your organization's security policies.
• Monitor API Key Usage: Pay attention to GitGuardian's audit logs and monitoring features to detect unusual activity associated with your API keys. Anomalous usage patterns could indicate a compromise.
• Enable Multi-Factor Authentication (MFA): For all human users accessing the GitGuardian dashboard, enable and enforce MFA. This significantly reduces the risk of account takeover, even if passwords are stolen.
• Secure CI/CD Environments: Ensure that your CI/CD pipelines, where GitGuardian API keys are often used, are themselves secured. This includes limiting access to pipeline configurations, using secure runners, and regularly patching systems.
• Delete Unused Keys: Regularly review your API keys in the GitGuardian dashboard and delete any that are no longer in use. This reduces the attack surface.
• Avoid Sharing Keys: Each user or service should have its own distinct API key. Avoid sharing keys among multiple users or services to maintain proper auditing and accountability.

By implementing these security best practices, organizations can significantly enhance the protection of their GitGuardian integrations and the sensitive data they protect.