GitGuardian API (1.1.0)
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.
- The base url for the latest version is
api.gitguardian.com/v1overHTTPS. - 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:
- Python: py-gitguardian
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
Response samples
- 200
- 401
{- "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"
]
}Response samples
- 401
{- "detail": "Invalid API key."
}List API tokens.
List all the tokens in the workspace, some filters are available and described below.
Authorizations:
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
- 200
- 400
- 401
[- {
- "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"
]
}
]Retrieve details of an API token.
Authorizations:
api_tokens:read) path Parameters
| token_id required | string Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360 Id of the token. |
Responses
Response samples
- 200
- 401
- 404
{- "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"
]
}Revoke an an API token.
Authorizations:
api_tokens:write) path Parameters
| token_id required | string Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360 Id of the token. |
Responses
Response samples
- 401
- 404
{- "detail": "Invalid API key."
}List secret incidents
List secret incidents detected by the GitGuardian dashboard. Occurrences are not returned in this route.
Authorizations:
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" "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. |
Responses
Response samples
- 200
- 400
- 401
- 503
[- {
- "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,
- "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"
], - "occurrences": null
}
]Retrieve a secret incident
Retrieve secret incident detected by the GitGuardian dashboard with its occurrences.
Authorizations:
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
- 200
- 400
- 401
- 503
{- "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,
- "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"
], - "occurrences": [
- {
- "id": 4421,
- "incident_id": 3759,
- "kind": "Realtime",
- "source": {
- "id": 6531,
- "type": "github",
- "full_name": "gitguardian/gg-shield",
- "health": "at_risk",
- "default_branch": "main",
- "default_branch_head": "abcd97b4aaf927ea934504263322e75e86c31xyz",
- "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",
- "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
}
], - "tags": [
- "FROM_HISTORICAL_SCAN",
- "SENSITIVE_FILE"
], - "sha": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
- "presence": "present",
- "filepath": "test_data/12123testfile.txt"
}
]
}Update a secret incident
Update a secret incident
Authorizations:
incidents:write) path Parameters
| incident_id required | integer The id of the incident to retrieve |