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

API Tokens

Manage API tokens.

Retrieve details of the current API token.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  • "name": "myTokenName",
  • "type": "personal_access_token",
  • "status": "revoked",
  • "created_at": "2023-05-20T12:40:55.662949Z",
  • "last_used_at": "2023-05-24T12:40:55.662949Z",
  • "expire_at": null,
  • "revoked_at": "2023-05-27T12:40:55.662949Z",
  • "member_id": 22015,
  • "creator_id": 22015,
  • "scopes": [
    ]
}

Revoke the current API token.

Authorizations:

Responses

Response samples

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

List API tokens.

List all the tokens in the workspace, some filters are available and described below.

Authorizations:
API Key (api_tokens:read)
query Parameters
cursor
string

Pagination cursor.

per_page
integer [ 1 .. 100 ]
Default: 20

Number of items to list per page.

status
string
Enum: "active" "expired" "revoked"

Status of the token.

member_id
integer
Example: member_id=1

Filter by member id.

creator_id
integer
Example: creator_id=1

Filter by creator id.

scopes
string
Enum: "scan" "incidents:read" "incidents:write" "incidents:share" "members:read" "members:write" "teams:read" "teams:write" "audit_logs:read" "honeytokens:read" "honeytokens:write" "api_tokens:read" "api_tokens:write"
Example: scopes=incidents:read,api_tokens:read

Tokens with one of the following scopes.

search
string

Search tokens based on their name.

ordering
string
Enum: "created_at" "-created_at" "last_used_at" "-last_used_at" "expire_at" "-expire_at" "revoked_at" "-revoked_at"

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details of an API token.

Authorizations:
API Key (api_tokens:read)
path Parameters
token_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

Content type
application/json
{
  • "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  • "name": "myTokenName",
  • "type": "personal_access_token",
  • "status": "revoked",
  • "created_at": "2023-05-20T12:40:55.662949Z",
  • "last_used_at": "2023-05-24T12:40:55.662949Z",
  • "expire_at": null,
  • "revoked_at": "2023-05-27T12:40:55.662949Z",
  • "member_id": 22015,
  • "creator_id": 22015,
  • "scopes": [
    ]
}

Revoke an an API token.

Authorizations:
API Key (api_tokens:write)
path Parameters
token_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

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

Secret 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:
API Key (incidents:read)
query Parameters
cursor
string

Pagination cursor.

page
integer >= 0
Deprecated
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.

assignee_email
string
Example: assignee_email=eric@gitguardian.com

Incidents assigned to this email.

assignee_id
integer
Example: assignee_id=4932

Incidents assigned to this user id.

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

Incidents with the following status.

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

Filter incidents by severity.

validity
string
Enum: "valid" "invalid" "failed_to_check" "no_checker" "unknown"

Secrets with the following validity.

tags
string
Enum: "FROM_HISTORICAL_SCAN" "IGNORED_IN_CHECK_RUN" "PUBLIC" "REGRESSION" "SENSITIVE_FILE" "TEST_FILE" "NONE"
Example: tags=FROM_HISTORICAL_SCAN,SENSITIVE_FILE

Incidents with one of the following tags. Use NONE if you want to filter incidents with no tags.

ordering
string
Enum: "date" "-date" "resolved_at" "-resolved_at" "ignored_at" "-ignored_at"

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.

detector_group_name
string
Example: detector_group_name=slackbot_token

Incidents belonging to the specified detector group.

ignorer_id
integer
Example: ignorer_id=4932

Incidents ignored by this user id.

ignorer_api_token_id
string <uuid>
Example: ignorer_api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8

Incidents ignored by this API token id.

resolver_id
integer
Example: resolver_id=4932

Incidents resolved by this user id.

resolver_api_token_id
string <uuid>
Example: resolver_api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8

Incidents resolved by this API token id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a secret incident

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

Authorizations:
API Key (incidents:read)
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
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "occurrences": [],
  • "ignore_reason": "test_credential",
  • "severity": "high",
  • "validity": "valid",
  • "ignored_at": "2019-08-24T14:15:22Z",
  • "ignorer_id": 309,
  • "ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
  • "resolver_id": 395,
  • "resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
  • "secret_revoked": false,
  • "resolved_at": null,
  • "tags": [
    ]
}

Update a secret incident

Update a secret incident

Authorizations:
API Key (incidents:write)
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
severity
string
Enum: "critical" "high" "medium" "low" "info" "unknown"

Responses

Request samples

Content type
application/json
{
  • "severity": "critical"
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "201