GitGuardian Getting Started: API & CLI Quickstart (2026)

Getting started overview

This guide outlines the initial steps for setting up GitGuardian to begin monitoring for exposed secrets. It covers account creation, API key generation, and executing a first request using either the GitGuardian API or its command-line interface (CLI). GitGuardian provides tools for developers to integrate secrets detection directly into their development workflows, including local scanning and CI/CD pipeline integration developer experience notes. The API supports custom integrations and automation.

To follow this guide, you will need a GitGuardian account. The process involves:

1. Creating a GitGuardian account.
2. Generating an API key from the GitGuardian dashboard.
3. Making an authenticated request using the API or CLI.

This table summarizes key steps:

Create an account and get keys

Access to GitGuardian's features, including its API and CLI, begins with creating an account. GitGuardian offers a free tier for individual developers and small teams GitGuardian pricing page, which can be used to get started.

Account Creation

1. Navigate to the GitGuardian website.
2. Click on the "Get Started Free" or "Sign Up" button.
3. Follow the prompts to create your account, which may include signing up with an email address or through a GitHub/GitLab account.
4. Complete any necessary email verification steps.

API Key Generation

After creating and logging into your GitGuardian account, you need to generate an API key. This key will authenticate your requests to the GitGuardian API and CLI.

1. From your GitGuardian dashboard, navigate to Settings.
2. Look for a section related to API Keys or Personal Access Tokens.
3. Click on "Generate new token" or "Create API Key".
4. Provide a descriptive name for your key (e.g., "APIspine Test Key").
5. Ensure the generated key has the necessary permissions for the operations you intend to perform. For initial testing, broad permissions might be acceptable, but for production, adhere to the principle of least privilege security best practices.
6. Copy the generated API key immediately. It is typically shown only once and cannot be retrieved later. Store it securely.

Your first request

Once you have your GitGuardian API key, you can make your first authenticated request. This section demonstrates how to do this using both the GitGuardian CLI (ggshield) and a direct API call via curl.

Option 1: Using the GitGuardian CLI (ggshield)

The GitGuardian CLI, ggshield, allows you to scan local files or repositories for secrets. First, install ggshield:

Installation

Using pip (Python package installer):

pip install ggshield

For other installation methods, refer to the ggshield installation guide.

Configuration with API Key

Set your GitGuardian API key as an environment variable or configure it directly:

export GG_API_KEY="<YOUR_GITGUARDIAN_API_KEY>"
ggshield auth login --token "<YOUR_GITGUARDIAN_API_KEY>"

Replace <YOUR_GITGUARDIAN_API_KEY> with the key you generated.

Performing a Scan

To perform a quick scan on a local file:

echo "My test secret: shpat_1234567890abcdef1234567890abcdef" > test_file.txt
ggshield scan path test_file.txt

This command will scan test_file.txt for common secret patterns. If a secret is detected (like the fake Shopify Access Token above), ggshield will report it.

Option 2: Direct API Call with curl

You can also interact with the GitGuardian API directly. For this example, we'll use the /v1/scan endpoint to scan a simple string.

API Endpoint

The base URL for the GitGuardian API is https://api.gitguardian.com.

Request Example

curl -X POST \  
  'https://api.gitguardian.com/v1/scan' \ 
  -H 'Accept: application/json' \ 
  -H 'Authorization: Token <YOUR_GITGUARDIAN_API_KEY>' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
    "documents": [ 
      { 
        "filename": "example.txt", 
        "content": "This is a test document with a potential secret: GH_PAT_abcdef1234567890abcdef1234567890" 
      } 
    ] 
  }'

Replace <YOUR_GITGUARDIAN_API_KEY> with your actual GitGuardian API key. The response will be a JSON object detailing any detected incidents, their severity, and suggested remediation steps. For more details on the API structure and available endpoints, consult the GitGuardian API reference documentation.

Common next steps

After successfully making your first request, consider these common next steps to integrate GitGuardian more deeply into your development workflow:

1. Integrate with Version Control Systems (VCS): Connect your GitHub, GitLab, or Bitbucket repositories to GitGuardian for continuous monitoring of new commits and historical scans. This is typically done through the GitGuardian dashboard's Integrations section GitGuardian platform integrations.
2. Set up CI/CD Integration: Integrate ggshield into your CI/CD pipelines (e.g., GitHub Actions, GitLab CI, Jenkins) to prevent secrets from being pushed into repositories during the build or deployment process. This helps enforce security policies pre-commit or pre-merge.
3. Explore Remediation Playbooks: Familiarize yourself with GitGuardian's automated remediation playbooks. These can help streamline the process of revoking compromised secrets and containing incidents.
4. Configure Alerting and Notifications: Set up custom alerts and integrate with communication platforms (e.g., Slack, PagerDuty, email) to ensure your team is promptly notified of any detected secrets.
5. Review Dashboard and Incidents: Regularly monitor your GitGuardian dashboard to review detected incidents, understand their context, and track remediation progress.
6. Define Custom Policies: Depending on your organization's specific needs, you might want to define custom detection policies to identify proprietary secret formats or sensitive data patterns beyond GitGuardian's default detectors.

Troubleshooting the first call

If you encounter issues during your first API or CLI call, consider the following common troubleshooting steps:

• API Key Validity: Ensure your API key is correct and hasn't expired or been revoked. Regenerate the key if necessary from your GitGuardian dashboard.
• Authorization Header: For API calls, verify that the Authorization: Token <YOUR_GITGUARDIAN_API_KEY> header is correctly formatted. There must be a space between Token and your key.
• Network Connectivity: Confirm that your machine has an active internet connection and can reach api.gitguardian.com. Proxy settings or firewalls might interfere with the connection.
• Content-Type Header: For POST requests to the API, ensure the Content-Type: application/json header is present and correctly formatted.
• JSON Payload Format: Double-check that your JSON payload in curl requests is valid and adheres to the API documentation's requirements. Syntax errors in JSON can lead to failed requests.
• CLI Configuration: If using ggshield, ensure your API key is correctly set as an environment variable (GG_API_KEY) or configured using ggshield auth login.
• CLI Version: Ensure your ggshield installation is up to date. You can update it using pip install --upgrade ggshield.
• Error Messages: Pay close attention to any error messages returned by the API or CLI. They often provide specific clues about what went wrong (e.g., "Unauthorized", "Bad Request"). Refer to the GitGuardian API error codes documentation for explanations of common errors.
• Documentation Review: Consult the official GitGuardian documentation for the specific endpoint or CLI command you are using.