GitGuardian API (1.0.2)

Download OpenAPI specification:Download

Introduction

Whether you want to build a complete integration with your software development workflow or simply want to test GitGuardian's policy break detection on any text content, you can use our API.

  • The base url for the latest version is api.gitguardian.com/v1 over HTTPS.
  • All data is sent and received as JSON by default.
  • All timestamps returned are ISO-8601 compliant, example:
    2020-03-16T04:46:00+00:00 # for date-time

GitGuardian supported wrappers:

GitGuardian provides you with GitGuardian Shield, a CLI application that uses the GitGuardian API through py-gitguardian to scan your files and detect potential secrets or issues in your code.

This CLI application can be used in many CIs (such as GitHub Actions, GitLab Pipelines, CircleCI,...) or as a pre-commit or pre-receive hook.

Authentication

The GitGuardian API uses API keys to authenticate requests.

You need to create an account before getting started in order to get an API key.

Your API key can be created and revoked from the API section of your dashboard.

Your API key must kept private and should neither be embedded directly in the code nor versioned in Git. (Please do not push GitGuardian's API keys to public GitHub repositories ^^).

Beware your API keys can expire and can be revoked.

Use /v1/health to check the validity of your token if needed.

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

API Key

Usage: Token <API Key> in authorization header.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "Token <API Key>"

Scanning

Use GitGuardian's brain at your leisure.

Scanning API allows you to scan any content you want using GitGuardian's secrets detection algorithms.

Content Scan

Scan provided document content for policy breaks.

Request body shouldn't exceed 1MB.

This endpoint is stateless and as such will not store in our servers neither the documents nor the secrets found.

Authorizations:
Request Body schema: application/json
filename
string <= 256 characters
document
required
string

Responses

Request samples

Content type
application/json
{
  • "filename": ".env",
  • "document": "\nimport urllib.request\nurl = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'\nresponse = urllib.request.urlopen(url)\nconsume(response.read())\n"
}

Response samples

Content type
application/json
{
  • "policy_break_count": 2,
  • "policies":
    [
    ],
  • "policy_breaks":
    [
    ]
}

Multiple Content Scan

Scan provided document contents for policy breaks. Multiple documents are returned by the same index order.

Request body shouldn't exceed 2MB and individual documents shouldn't exceed 1MB.

This endpoint is stateless and as such will not store in our servers neither the documents nor the secrets found.

Authorizations:
Request Body schema: application/json
Array ()
filename
string <= 256 characters
document
required
string

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Health Check

Check the status of the API and your token without spending your quota.

Authorizations:

Responses

Request samples

curl --request GET \
    --url https://api.gitguardian.com/v1/health \
    --header 'authorization: Token <Insert API Key>'

Response samples

Content type
application/json
{
  • "detail": "Valid API key."
}