Download OpenAPI specification:Download
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.
api.gitguardian.com/v1
over HTTPS
.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.
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
{- "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": [
- "incidents:read",
- "scan"
]
}
{- "detail": "Invalid API key."
}
List all the tokens in the workspace, some filters are available and described below.
api_tokens:read
) 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 '-'. |
[- {
- "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": [
- "incidents:read",
- "scan"
]
}
]
api_tokens:read
) token_id required | string Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360 Id of the token. |
{- "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": [
- "incidents:read",
- "scan"
]
}
api_tokens:write
) token_id required | string Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360 Id of the token. |
{- "detail": "Invalid API key."
}
List secret incidents detected by the GitGuardian dashboard. Occurrences are not returned in this route.
incidents:read
) 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 |
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. |
[- {
- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": null,
- "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,
- "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
]
Retrieve secret incident detected by the GitGuardian dashboard with its occurrences.
incidents:read
) incident_id required | integer The id of the incident to retrieve |
with_occurrences | integer [ 0 .. 100 ] Default: 20 Retrieve a number of occurrences of this incident. |
{- "id": 3759,
- "date": "2019-08-22T14:15:22Z",
- "detector": {
- "name": "slack_bot_token",
- "display_name": "Slack Bot Token",
- "nature": "specific",
- "family": "apikey",
- "detector_group_name": "slackbot_token",
- "detector_group_display_name": "Slack Bot Token"
}, - "secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
- "regression": false,
- "status": "IGNORED",
- "assignee_id": 309,
- "assignee_email": "eric@gitguardian.com",
- "occurrences_count": 4,
- "occurrences": [
- {
- "id": 4421,
- "incident_id": 3759,
- "kind": "Realtime",
- "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
- "source": {
- "id": 6531,
- "type": "github",
- "full_name": "gitguardian/gg-shield",
- "health": "at_risk",
- "open_incidents_count": 3,
- "closed_incidents_count": 2,
- "visibility": "public",
- "external_id": "125",
- "last_scan": {
- "date": "2021-05-20T12:40:55.662949Z",
- "status": "finished"
}
}, - "author_name": "Eric",
- "author_info": "eric@gitguardian.com",
- "date": "2021-05-20T12:40:55.662949Z",
- "presence": "present",
- "matches": [
- {
- "name": "apikey",
- "indice_start": 32,
- "indice_end": 79,
- "pre_line_start": null,
- "pre_line_end": null,
- "post_line_start": 1,
- "post_line_end": 1
}
], - "filepath": "test_data/12123testfile.txt"
}
], - "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": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
]
}
Update a secret incident
incidents:write
) incident_id required | integer The id of the incident to retrieve |
severity | string Enum: "critical" "high" "medium" "low" "info" "unknown" |
{- "severity": "critical"
}
{- "id": 3759,
- "date": "201