GitGuardian
Documentation Powered by ReDoc

GitGuardian API (1.1.0)

Download OpenAPI specification:Download

GitGuardian: support@gitguardian.com URL: https://www.gitguardian.com License: GitGuardian Terms of Service

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:
API Key

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:
API Key

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

Create a JSON Web Token.

Create a short lived JWT for authentication to specific GitGuardian services, including HasMySecretLeaked.

Authorizations:
API Key
Request Body schema: application/json
audience
required
string

Audience of the JWT.

audience_type
string

Type of audience.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJS[...]"
}

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: DEFAULT_BRANCH FROM_HISTORICAL_SCAN IGNORED_IN_CHECK_RUN PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED 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",
  • "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3899",
  • "regression": false,
  • "status": "IGNORED",
  • "assignee_id": 309,
  • "assignee_email": "eric@gitguardian.com",
  • "occurrences_count": 4,
  • "ignore_reason": "test_credential",
  • "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,
  • "severity": "high",
  • "validity": "valid",
  • "resolved_at": null,
  • "share_url": "https://dashboard.gitguardian.com/share/incidents/11111111-1111-1111-1111-111111111111",
  • "tags": [
    ],
  • "occurrences": [