GitGuardian API (1.1.0)

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>"

Incidents

Manage incidents found by post-receive hooks on your GitGuardian Dashboard.

List Secret Incidents

List secret incidents detected by the GitGuardian dashboard. Occurrences are not returned in this route.

Authorizations:
query Parameters
page
integer >= 0
Default: 1

Page number.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

date_before
string <datetime>
Example: date_before=2019-08-30T14:15:22Z

Entries found before this date.

date_after
string <datetime>
Example: date_after=2019-08-22T14:15:22Z

Entries found after this date.

status
string
Enum: "IGNORED" "TRIGGERED" "ASSIGNED" "RESOLVED"

Incidents with the following status.

assignee_email
string
Example: assignee_email=toto@gitguardian.com

Incidents assigned to this email.

severity
string
Enum: "critical" "high" "medium" "low" "info" "unknown"

Filter incidents by severity.

validity
string
Enum: "valid" "invalid" "unknown" "cannot_check"

Secrets with the following validity.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Secret Incident

Retrieve secret incident detected by the GitGuardian dashboard with its occurrences.

Authorizations:
path Parameters
incident_id
required
integer

The id of the incident to retrieve

query Parameters
with_occurrences
integer [ 0 .. 100 ]
Default: 20

Retrieve a number of occurrences of this incident.

Responses

Response samples

Content type
application/json
{}

Assign Secret Incident

Assign secret incident detected by the GitGuardian dashboard to a workspace member by email.

Authorizations:
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "toto@gitguardian.com"
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_email": "toto@gitguardian.com",
  • "occurrence_count": 4,
  • "occurrences": null,
  • "ignore_reason": "test_credential",
  • "ignored_at": "2019-08-24T14:15:22Z",
  • "secret_revoked": false,
  • "severity": "high",
  • "validity": "valid",
  • "resolved_at": null,
}

Unassign Secret Incident

Unassign secret incident from a workspace member by email.

Authorizations:
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_email": "toto@gitguardian.com",
  • "occurrence_count": 4,
  • "occurrences": null