GitGuardian API (1.1.0)

Download OpenAPI specification:

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 https://api.gitguardian.com/v1 or https://api.eu1.gitguardian.com/v1 depending on your location.
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.

Authentication

The GitGuardian API uses API keys to authenticate requests. For a detailed explanation, please refer to our dedicated documentation.

Use /v1/health to check the validity of your token if needed.

Pagination

The GitGuardian API employs cursor-based pagination. For a detailed explanation, please refer to our dedicated documentation.

Audit Logs

List audit Logs

List audit logs.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
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.
event_name	string Example: event_name=user.logged_in Entries matching this event name.
member_id	integer Example: member_id=3252 The id of the member to retrieve.
member_name	string Example: member_name=John Smith Entries matching this member name.
member_email	string Example: member_email=john.smith@example.org Entries matching this member email.
api_token_id	string <uuid> Example: api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8 Entries matching this API token id.
ip_address	string Example: ip_address=8.8.8.8 Entries matching this IP address.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"id": 3759,
"date": "2019-08-22T14:15:22Z",
"member_email": "eric@gitguardian.com",
"member_name": "Eric",
"member_id": 1243,
"api_token_id": "41f016f9-d44b-451c-a816-df041c057c6b",
"ip_address": "string",
"target_ids": ["1243",
"2bb559aa-bd72-48ca-b4ba-bf09b1c9a658"
],
"action_type": "READ",
"event_name": "user.logged_in",
"data": "{type: github_sso}"
}
]

Custom Tags

Manage custom tags. Linking a custom tag to resources occurs at the resource endpoints themselves. For example, you can apply a custom tag to an incident here or to a honeytoken here.

List custom tags

List all existing custom tags.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
key	string Example: key=env Filter on the specified custom tag key

Responses

Response samples

Content type

application/json

[{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]

Create a custom tag

This endpoint allows you to create a custom tag.

Authorizations:

api-key

Request Body schema: application/json
required

key	string
value	string or null

Responses

Request samples

Payload

Content type

application/json

{"key": "env",
"value": "prod"
}

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}

Update custom tags key

This endpoint allows you to update a key for all custom tags using it.

Authorizations:

api-key

query Parameters

old_key required	string Example: old_key=env Existing key to be renamed
new_key required	string Example: new_key=environment New name of the key

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Delete a custom tags key

This endpoint allows you to delete all custom tags using the given key.

Authorizations:

api-key

query Parameters

key

required

string

Example: key=env

Key to be deleted

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Retrieve a custom tag

This endpoint allows you to retrieve an existing custom tag.

Authorizations:

api-key

path Parameters

custom_tag_id

required

string <uuid>

The id of the custom tag

Responses

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}

Full Update of a Custom Tag

This endpoint allows you to update a specific custom tag. It replaces the entire custom tag (key and value).

This does not impact other custom tags sharing the same key.

Authorizations:

api-key

path Parameters

custom_tag_id

required

string <uuid>

The id of the custom tag

Request Body schema: application/json

key	string
value	string or null

Responses

Request samples

Payload

Content type

application/json

{"key": "env",
"value": "prod"
}

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}

Partial update of a Custom Tag

This endpoint allows you to partially update a specific custom tag. It updates only the specified fields (key or value), leaving the other fields unchanged.

This does not impact other custom tags sharing the same key.

Authorizations:

api-key

path Parameters

custom_tag_id

required

string <uuid>

The id of the custom tag

Request Body schema: application/json

key	string
value	string or null

Responses

Request samples

Payload

Content type

application/json

{"key": "env",
"value": "prod"
}

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}

Deletion of a custom tag

This endpoint allows you to delete a specific custom tag.

This does not impact other custom tags sharing the same key.

Authorizations:

api-key

path Parameters

custom_tag_id

required

string <uuid>

The id of the custom tag

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Honeytokens

Manage honeytokens.

List honeytokens

This endpoint allows you to list all the honeytokens of your workspace.

The response contains the list of honeytokens and a pagination cursor to retrieve the next page.

The honeytokens are sorted by id.

If you are using a personal access token, you need to have an access level superior or equal to manager.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
status	string Enum: triggered active revoked Status of a honeytoken.
type	string Value: AWS Type of a honeytoken.
search	string Search honeytokens based on their name and/or description.
creator_id	number Member id of the honeytoken creator.
revoker_id	number Member id of the honeytoken revoker.
creator_api_token_id	string Token id of the honeytoken creator.
revoker_api_token_id	string Token id of the honeytoken creator.
tags	string Comma-separated list of tags to filter on.
ordering	string Enum: created_at -created_at triggered_at -triggered_at revoked_at -revoked_at name -name Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
show_token	boolean Default: false Show token details (`access_token_id` and `secret_key`).

Responses

Response samples

200
400
401
403
503

Content type

application/json

[{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"name": "honeytoken A",
"description": "honeytoken used in the repository AA",
"created_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "active",
"triggered_at": "2019-08-22T14:15:22Z",
"revoked_at": "2019-08-22T14:15:22Z",
"open_events_count": 122,
"type": "AWS",
"creator_id": 122,
"revoker_id": 122,
"creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
"revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
"token": {"access_token_id": "AAAA",
"secret_key": "BBB"
},
"tags": ["publicly_exposed"
],
"labels": [{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}
]

Create a honeytoken

This endpoint allows you to create a honeytoken of a type.

If you are using a personal access token, you need to have an access level superior or equal to manager.

Authorizations:

api-key

Request Body schema: application/json

name required	string honeytoken name.
description	string honeytoken description.
type required	string Value: AWS honeytoken type
	Array of objects (Honeytoken Label) Deprecated Custom tags to set on the honeytoken. If the custom tag doesn't exist, it will be created. This field is deprecated; use the `custom_tags` field instead.
	Array of objects Custom tags to set on the honeytoken. If the custom tag doesn't exist, it will be created.

Responses

Request samples

Payload

Content type

application/json

{"name": "honeytoken name",
"description": "This honeytoken was placed in the repository test",
"type": "AWS",
"labels": [{"key": "env",
"value": "production"
}
],
"custom_tags": [{"key": "env",
"value": "prod"
}
]
}

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"name": "honeytoken A",
"description": "honeytoken used in the repository AA",
"created_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "active",
"triggered_at": "2019-08-22T14:15:22Z",
"revoked_at": "2019-08-22T14:15:22Z",
"open_events_count": 122,
"type": "AWS",
"creator_id": 122,
"revoker_id": 122,
"creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
"revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
"token": {"access_token_id": "AAAA",
"secret_key": "BBB"
},
"tags": ["publicly_exposed"
],
"labels": [{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Create a honeytoken within a context

This endpoint allows you to create a honeytoken of a given type within a context. The context is a realistic file in which your honeytoken is inserted.

If language, project_extensions and filename are not provided, a random context will be generated.

Authorizations:

api-key

Request Body schema: application/json

name required	string Honeytoken name.
description	string Honeytoken description.
type required	string Value: AWS Honeytoken type.
	Array of objects (Honeytoken Label) Labels to set on the honeytoken. If the label doesn't exist, it will be created.
language	string Language to use for the context. If not set but `project_extensions` is set, the languages will be inferred from the extensions.
filename	string Filename to use for the context.
project_extensions	Array of strings An array of file extensions that can be used for the context.

Responses

Request samples

Payload

Content type

application/json

{"name": "honeytoken name",
"description": "This honeytoken was placed in the repository test",
"type": "AWS",
"labels": [{"key": "env",
"value": "production"
}
],
"language": "python",
"filename": "test_config.py",
"project_extensions": [".c",
".h"
]
}

Response samples

Content type

application/json

{"content": "string",
"filepath": "config_prod.py",
"language": "python",
"suggested_commit_message": "adding test config",
"honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/honeytokens/948025a2-6969-493c-8696-3849c1e9f769"
}

Retrieve a honeytoken

Retrieve an existing honeytoken.

If you are using a personal access token, you need to have an access level greater or equal to manager.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

query Parameters

show_token

boolean

Default: false

Show token details (access_token_id and secret_key).

Responses

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"name": "honeytoken A",
"description": "honeytoken used in the repository AA",
"created_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "active",
"triggered_at": "2019-08-22T14:15:22Z",
"revoked_at": "2019-08-22T14:15:22Z",
"open_events_count": 122,
"type": "AWS",
"creator_id": 122,
"revoker_id": 122,
"creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
"revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
"token": {"access_token_id": "AAAA",
"secret_key": "BBB"
},
"tags": ["publicly_exposed"
],
"labels": [{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Update a honeytoken

Update a name or descriptions of an existing honeytoken.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

Request Body schema: application/json

name	string A new honeytoken name
description	string A new honeytoken description
	Array of objects (Honeytoken Label) Deprecated A new set of custom tags for the honeytoken. Will completely override the former custom tags. This field is deprecated; use the `custom_tags` field instead.
	Array of objects A new set of custom tags for the honeytoken. Will completely override the former custom tags.

Responses

Request samples

Payload

Content type

application/json

{"name": "test-honeytoken",
"description": "honeytoken in repository test",
"labels": [{"key": "env",
"value": "production"
}
],
"custom_tags": [{"key": "env",
"value": "prod"
}
]
}

Response samples

200
400
401
503

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"name": "honeytoken A",
"description": "honeytoken used in the repository AA",
"created_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "active",
"triggered_at": "2019-08-22T14:15:22Z",
"revoked_at": "2019-08-22T14:15:22Z",
"open_events_count": 122,
"type": "AWS",
"creator_id": 122,
"revoker_id": 122,
"creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
"revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
"token": {"access_token_id": "AAAA",
"secret_key": "BBB"
},
"tags": ["publicly_exposed"
],
"labels": [{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Reset the honeytoken

Resets a triggered honeytoken. All the associated events will be closed.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

Responses

Response samples

200
400
401
503

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"name": "honeytoken A",
"description": "honeytoken used in the repository AA",
"created_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "active",
"triggered_at": "2019-08-22T14:15:22Z",
"revoked_at": "2019-08-22T14:15:22Z",
"open_events_count": 122,
"type": "AWS",
"creator_id": 122,
"revoker_id": 122,
"creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
"revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
"token": {"access_token_id": "AAAA",
"secret_key": "BBB"
},
"tags": ["publicly_exposed"
],
"labels": [{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Revoke the honeytoken

Revokes an active or triggered honeytoken. All the associated events will be closed.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

Responses

Response samples

200
400
401
503

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"name": "honeytoken A",
"description": "honeytoken used in the repository AA",
"created_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "active",
"triggered_at": "2019-08-22T14:15:22Z",
"revoked_at": "2019-08-22T14:15:22Z",
"open_events_count": 122,
"type": "AWS",
"creator_id": 122,
"revoker_id": 122,
"creator_api_token_id": "f74ffca5-d06d-45c2-a3d8-e8e95d15a464",
"revoker_api_token_id": "19058e4a-0fab-4dcc-8ed6-4e2ec9fb2e44",
"token": {"access_token_id": "AAAA",
"secret_key": "BBB"
},
"tags": ["publicly_exposed"
],
"labels": [{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Honeytokens Events

Manage events on honeytokens.

List all honeytokens events

List events related to all honeytokens of the workspace.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
ordering	string Enum: triggered_at -triggered_at Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'
honeytoken_id	string <uuid> Example: honeytoken_id=d45a123f-b15d-4fea-abf6-ff2a8479de5b Filter by honeytoken id
status	string Default: open Enum: open archived allowed Filter by status
ip_address	string Example: ip_address=8.8.8.8 Filter by ip address
tags	string Comma-separated list of tags to filter on
search	string Example: search=I revoked this Search events based on the `data` field content

Responses

Response samples

200
400
401
503

Content type

application/json

[{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"triggered_at": "2019-08-22T14:15:22Z",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/3bf0ed1b-68b2-4db8-b944-d450c5d35cf4",
"status": "open",
"ip_address": "8.8.8.8",
"action": "string",
"data": { },
"tags": ["publicly_exposed"
]
}
]

Honeytoken Notes

Manage notes on honeytokens.

List notes on an honeytoken

List notes left on a honeytoken in chronological order.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
ordering	string Enum: created_at -created_at updated_at -updated_at Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
member_id	integer Example: member_id=1 Filter by member id.
api_token_id	string <uuid> Example: api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8 Entries matching this API token id.
search	string Example: search=I revoked this Search notes based on the comment field content.

Responses

Response samples

200
400
401
404
503

Content type

application/json

[{"id": "1b99892e-6254-4f8a-9e98-559ed810b7da",
"honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"member_id": 38,
"api_token_id": "37d5b0d7-9f89-4b80-9070-261e26637836",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret"
}
]

Create an honeytoken note

Add a note on a honeytoken.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

Request Body schema: application/json

comment

required

string <= 10000 characters

Content of the honeytoken note

Responses

Request samples

Payload

Content type

application/json

{"comment": "I revoked this honeytoken"
}

Response samples

201
400
401
404
503

Content type

application/json

{"id": "1b99892e-6254-4f8a-9e98-559ed810b7da",
"honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"member_id": 38,
"api_token_id": "37d5b0d7-9f89-4b80-9070-261e26637836",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret"
}

Update a honeytoken note

Update an existing comment on a honeytoken. Only honeytoken notes created by the current API key can be updated.

Authorizations:

api-key

path Parameters

honeytoken_id required	string <uuid> The id of the honeytoken to retrieve
note_id required	string <uuid> The id of the honeytoken note to update

Request Body schema: application/json

comment

required

string <= 10000 characters

Content of the honeytoken note

Responses

Request samples

Payload

Content type

application/json

{"comment": "I revoked this"
}

Response samples

Content type

application/json

{"id": "1b99892e-6254-4f8a-9e98-559ed810b7da",
"honeytoken_id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"member_id": 38,
"api_token_id": "37d5b0d7-9f89-4b80-9070-261e26637836",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret"
}

Delete a honeytoken note

Delete an existing comment on a honeytoken. Only honeytoken notes created by the current API key can be deleted.

Authorizations:

api-key

path Parameters

honeytoken_id required	string <uuid> The id of the honeytoken to retrieve
note_id required	string <uuid> The id of the honeytoken note to update

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Honeytoken Sources

Manage sources on honeytokens.

List sources on an honeytoken

List sources where a honeytoken appears.

Authorizations:

api-key

path Parameters

honeytoken_id

required

string <uuid>

The id of the honeytoken to retrieve

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
ordering	string Enum: source_id -source_id 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
404
503

Content type

application/json

[{"type": "github",
"name": "gitguardian/gg-shield",
"url": "https://github.com/GitGuardian/gg-shield",
"open_issues_count": 3,
"total_files_count": 2,
"files": [".env"
],
"source_id": 0
}
]

Labels

Manage labels for honeytokens. Labels provide a flexible way to organize honeytokens. You can create your own labels in the form of keys and values, assign them to honeytokens, and use them to filter and search for honeytokens based on specific characteristics.

List labels Deprecated

List labels created for honeytokens in chronological order.

DEPRECATED: This endpoint has been replaced by this one as per introduction of the custom tags feature.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Example: search=env:production Search string to filter only labels which contains the search string in either its key or value. The search string can also be in the key:value format.
key	string Example: key=env Filter only labels which have the given key.

Responses

Response samples

200
400
401
403
503

Content type

application/json

[{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}
]

Create a label Deprecated

Create a label for honeytokens.

DEPRECATED: This endpoint has been replaced by this one as per introduction of the custom tags feature.

Authorizations:

api-key

Request Body schema: application/json

key required	string Label's key's content.
value required	string Label's value's content.

Responses

Request samples

Payload

Content type

application/json

{"key": "env",
"value": "production"
}

Response samples

201
400
401
403
503

Content type

application/json

{"id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
"key": "env",
"value": "production"
}

Update a key Deprecated

Rename a label key. It will be renamed in all the labels using this key.

DEPRECATED: This endpoint has been replaced by this one as per introduction of the custom tags feature.

Authorizations:

api-key

query Parameters

old_key required	string Example: old_key=env an existing key that we want to rename
new_key required	string Example: new_key=env prod a new name of the key

Responses

Response samples

400
401
403
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Delete a key Deprecated

Delete a key. All the labels using this key will be deleted.

DEPRECATED: This endpoint has been replaced by this one as per introduction of the custom tags feature.

Authorizations:

api-key

query Parameters

key	string Example: key=env A specified key to use to delete all labels which have the key matched.

Responses

Response samples

400
401
403
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Update a value Deprecated

Rename the value of a label.

DEPRECATED: This endpoint has been replaced by this one as per introduction of the custom tags feature.

Authorizations:

api-key

path Parameters

label_id

required

string

Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the label.

Request Body schema: application/json

value

required

string

New value for the label.

Responses

Request samples

Payload

Content type

application/json

{"value": "production"
}

Response samples

400
401
403
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Delete a label Deprecated

Delete a label for honeytokens.

DEPRECATED: This endpoint has been replaced by this one as per introduction of the custom tags feature.

Authorizations:

api-key

path Parameters

label_id

required

string

Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the label.

Responses

Response samples

401
403
404
503

Content type

application/json

{"detail": "Invalid API key."
}

IP Allowlist

Manage the IP allowlist for workspace access. Only available on SaaS.

List IP allowlist rules

This endpoint allows you to list all the IP allowlist rules of your workspace.

The response contains the list of IP allowlist rules and a pagination cursor to retrieve the next page.

If you are using a personal access token, you need to have an access level superior or equal to manager.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Search IP allowlist rules based on their tag and/or the IP ranges.
ordering	string Enum: created_at -created_at tag -tag 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
403
503

Content type

application/json

[{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"tag": "Main office",
"created_at": "2019-08-22T14:15:22Z",
"ip_ranges": ["35.153.173.97",
"10.0.0.0/24"
]
}
]

Create an IP allowlist rule

This endpoint allows you to create an IP allowlist rule.

If you are using a personal access token, you need to have an access level superior or equal to manager.

Authorizations:

api-key

Request Body schema: application/json

tag required	string <= 48 characters Tag for the IP allowlist rule
ip_ranges required	Array of strings The IP addresses (individual IPs or CIDR notation) to include in the IP allowlist rule

Responses

Request samples

Payload

Content type

application/json

{"tag": "Main office",
"ip_ranges": ["35.153.173.97",
"10.0.0.0/24"
]
}

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"tag": "Main office",
"created_at": "2019-08-22T14:15:22Z",
"ip_ranges": ["35.153.173.97",
"10.0.0.0/24"
]
}

Retrieve an IP allowlist rule

Retrieve an existing IP allowlist rule.

If you are using a personal access token, you need to have an access level greater or equal to manager.

Authorizations:

api-key

path Parameters

ip_allowlist_rule_id

required

string <uuid>

The id of the IP allowlist rule

Responses

Response samples

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"tag": "Main office",
"created_at": "2019-08-22T14:15:22Z",
"ip_ranges": ["35.153.173.97",
"10.0.0.0/24"
]
}

Update an IP allowlist rule

Update the tag or the IP ranges of an existing IP allowlist rule.

Authorizations:

api-key

path Parameters

ip_allowlist_rule_id

required

string <uuid>

The id of the IP allowlist rule

Request Body schema: application/json

tag	string <= 48 characters A new tag
ip_ranges	Array of strings The IP addresses (individual IPs or CIDR notation) to include in the IP allowlist rule

Responses

Request samples

Payload

Content type

application/json

{"tag": "Satellite office",
"ip_ranges": ["35.45.64.56",
"10.0.0.0/24"
]
}

Response samples

200
400
401
503

Content type

application/json

{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"tag": "Main office",
"created_at": "2019-08-22T14:15:22Z",
"ip_ranges": ["35.153.173.97",
"10.0.0.0/24"
]
}

Delete an IP allowlist rule

Delete an existing IP allowlist rule.

Authorizations:

api-key

path Parameters

ip_allowlist_rule_id

required

string <uuid>

The id of the IP allowlist rule

Responses

Response samples

401
403
404
503

Content type

application/json

{"detail": "Invalid API key."
}

Internal Secret Incidents

List secret incidents

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

Authorizations:

api-key

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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
exclude_tags	string Enum: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED NONE Example: exclude_tags=TEST_FILE,FALSE_POSITIVE Exclude incidents with any of the following tags (comma-separated). Use `NONE` to exclude incidents with no tags.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Incidents with the given custom tag key.
custom_tag_value	string Incidents with the given custom tag value.
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.
feedback	boolean Incidents with or without feedback.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

Retrieve a secret incident

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

Authorizations:

api-key

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

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": [{"id": 4421,
"incident_id": 3759,
"kind": "realtime",
"source": {"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
},
"author_name": "Eric",
"author_info": "eric@gitguardian.com",
"date": "2021-05-20T12:40:55.662949Z",
"url": "https://github.com/prm-dev-team/QATest_staging/commit/76dd18a2a8d27eaf00a45851cc7731c53b59ed19#diff-0f372f3171c8f13a15a22a1081487ed54fa70ad088e17c6c6386196a179a04ffR1",
"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:

api-key

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
	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"severity": "high",
"custom_tags": [{"key": "env",
"value": "prod"
}
]
}

Response samples

200
400
401
503

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}

Retrieve where a secret has been publicly leaked

Retrieve where a secret has been publicly leaked.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
401
404
503

Content type

application/json

[{"source": "github",
"name": "GitGuardian / ggshield",
"url": "https://github.com/GitGuardian/ggshield/blob/1f8cd3497aa9acabaafb1851039be2c63448c2f9/README.md?plain=1#L5"
}
]

Assign a secret incident

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

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

send_email

boolean

Default: true

Whether to notify the assignee.

Request Body schema: application/json

email	string email of the member to assign. This parameter is mutually exclusive with `member_id`.
member_id	number id of the member to assign. This parameter is mutually exclusive with `email`.

Responses

Request samples

Payload

Content type

application/json

{"email": "eric@gitguardian.com",
"member_id": 4295
}

Response samples

200
400
401
409
503

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}

Unassign a secret incident

Unassign secret incident from a workspace member by email.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
400
401
409
503

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}

Resolve a secret incident

Resolve a secret incident detected by the GitGuardian dashboard.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

secret_revoked

required

boolean

Responses

Request samples

Payload

Content type

application/json

{"secret_revoked": true
}

Response samples

200
400
401
409
503

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}

Ignore a secret incident

Ignore a secret incident detected by the GitGuardian dashboard.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

ignore_reason

required

string

Enum: test_credential false_positive low_risk invalid

Responses

Request samples

Payload

Content type

application/json

{"ignore_reason": "low_risk"
}

Response samples

200
400
401
409
503

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}

Reopen a secret incident

Unresolve or unignore a secret incident detected by the GitGuardian dashboard.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
400
401
409
503

Content type

application/json

{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}

Unshare a secret incident

Unshare a secret incident by revoking its public link.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

400
401
409
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Grant access to a secret incident Deprecated

Grant a user, an existing invitee or a team access to a secret incident.

DEPRECATED: This endpoint has been replaced by this one for members, this one for teams, and this one for invitations.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

email	string Email address of a user or invitee. This parameter is mutually exclusive with `member_id`, `invitation_id` and `team_id`.
member_id	number Id of a member. This parameter is mutually exclusive with `email`, `invitation_id` and `team_id`.
invitation_id	number Id of an invitation. This parameter is mutually exclusive with `email`, `member_id` and `team_id`.
team_id	number Id of a team, except for the global team. This parameter is mutually exclusive with `email`, `member_id` and `invitation_id`.
incident_permission	string Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"member_id": 1492,
"incident_permission": "can_edit"
}

Response samples

400
401
403
409
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Revoke access to a secret incident Deprecated

Revoke access of a user, an existing invitee or a team to a secret incident.

DEPRECATED: This endpoint has been replaced by this one for members, this one for teams, and this one for invitations.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

email	string Email address of a user or invitee. This parameter is mutually exclusive with `member_id`, `invitation_id` and `team_id`.
member_id	number Id of a member. This parameter is mutually exclusive with `email`, `invitation_id` and `team_id`.
invitation_id	number Id of an invitation. This parameter is mutually exclusive with `email`, `member_id` and `team_id`.
team_id	number Id of a team, except for the global team. This parameter is mutually exclusive with `email`, `member_id` and `invitation_id`.

Responses

Request samples

Payload

Content type

application/json

{"member_id": 1492
}

Response samples

400
401
403
409
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

List members having access to a secret incident Deprecated

List all the members having access to a secret incident.

DEPRECATED: This endpoint has been replaced by /v1/secret-incidents/{incident_id}/members

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

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.
member_id	number Example: member_id=1234 filter on a specific member id.
incident_permission	string Enum: can_view can_edit full_access Example: incident_permission=can_view
role	string Deprecated Enum: owner manager member restricted Filter members based on their access level.
search	string Deprecated Search members based on their name or email.

Responses

Response samples

200
400
401
404
503

Content type

application/json

[{"member_id": 3252,
"incident_id": 3252,
"incident_permission": "can_edit",
"id": 1234,
"name": "John Smith",
"email": "john.smith@example.org",
"role": "owner"
}
]

List teams having access to a secret incident Deprecated

List all the teams having access to a secret incident.

DEPRECATED: This endpoint has been replaced by /v1/secret-incidents/{incident_id}/teams

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
team_id	number Example: team_id=1234 filter on a specific team id.
incident_permission	string Enum: can_view can_edit full_access Example: incident_permission=can_view

Responses

Response samples

Content type

application/json

[{"team_id": 3252,
"incident_id": 3252,
"incident_permission": "can_edit"
}
]

List invitations having access to a Secret Incident Deprecated

List all the invitations having access to a Secret Incident.

DEPRECATED: This endpoint has been replaced by /v1/secret-incidents/{incident_id}/invitations

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
invitation_id	number Example: invitation_id=1234 filter on a specific invitation id.
incident_permission	string Enum: can_view can_edit full_access Example: incident_permission=can_view filter accesses with a specific permission.

Responses

Response samples

Content type

application/json

[{"invitation_id": 3252,
"incident_id": 3252,
"incident_permission": "can_edit"
}
]

Retrieve the impacted perimeter of a secret incident

Retrieve metrics about the impacted perimeter of a secret incident detected by the GitGuardian dashboard.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
400
401
503

Content type

application/json

{"id": 1,
"status": "TRIGGERED",
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"sources": [{"id": 1,
"url": "https://github.com/GitGuardian/ggshield/",
"type": "github",
"full_name": "GitGuardian/ggshield",
"files": {"files_requiring_code_fix": [{"filepath": "foo.txt",
"mentions_count": 1,
"file_url": "https://github.com/GitGuardian/ggshield/blob/main/foo.txt"
}
],
"files_pending_merge": [{"filepath": "bar.txt",
"mentions_count": 1,
"file_url": "https://github.com/GitGuardian/ggshield/blob/main/bar.txt"
}
],
"files_fixed": [{"filepath": "baz.txt",
"mentions_count": 1,
"merge_request_url": "https://github.com/GitGuardian/ggshield/pull/123"
}
]
}
}
]
}

List members with access to a secret incident

List members that have access to a secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
role	string Deprecated Enum: owner manager member restricted Filter members based on their access level. Use `access_level` instead.
access_level	string Enum: owner manager member restricted Filter members based on their access level.
search	string Search members based on their name or email.
ordering	string Enum: created_at -created_at last_login -last_login Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
direct_access	boolean Filter on direct or indirect accesses.

Responses

Response samples

Content type

application/json

[{"id": 3252,
"name": "John Smith",
"email": "john.smith@example.org",
"role": "owner",
"access_level": "owner",
"active": true,
"created_at": "2023-06-28T16:40:26.897Z",
"last_login": "2023-06-28T16:40:26.897Z"
}
]

List teams with access to a secret incident

List teams that have access to a secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Search teams based on their name and/or description.
direct_access	boolean Filter on direct or indirect accesses.

Responses

Response samples

Content type

application/json

[{"id": 3252,
"name": "feature team A",
"description": "Description of my team",
"is_global": false,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/settings/user/teams/1",
"external_provider_id": "123-456-7890"
}
]

List invitations with access to a secret incident

List invitations that have access to a secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Search invitations based on the email field.
ordering	string Enum: date -date Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
direct_access	boolean Filter on direct or indirect accesses.

Responses

Response samples

Content type

application/json

[{"id": 3252,
"email": "john.smith@example.org",
"role": "manager",
"access_level": "manager",
"date": "2019-08-22T14:15:22Z"
}
]

Retrieve a secret value

Retrieve the information, including its clear text value, of a secret by its ID.

Prerequisites:

This endpoint must be enabled in the workspace settings under Security by a workspace admin.
A valid API key with the secrets:read scope. This scope is available only for Personal Access Tokens (PATs).

Authorizations:

api-key

path Parameters

secret_id

required

integer

The ID of the secret to retrieve

Responses

Response samples

200
400
401
404
503

Content type

application/json

{"id": 37,
"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"
},
"matches": {"apikey": "sk-xxxxxxxxxxxxxxxx"
}
}

List secret incidents of a source

List secret incidents linked to a source. Occurrences are not returned in this route.

Authorizations:

api-key

path Parameters

source_id

required

integer

Example: 5523

The id of the source to filter on.

query Parameters

cursor	string Pagination cursor.
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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Incidents with the given custom tag key.
custom_tag_value	string Incidents with the given custom tag value.
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.
feedback	boolean Incidents with or without feedback.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

List secret incidents of a team Deprecated

List secret incidents of a particular team. Occurrences are not returned in this route.

DEPRECATED: THis endpoint has been replaced by /v1/teams/{team_id}/secret-incidents

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

cursor	string Pagination cursor.
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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Incidents with the given custom tag key.
custom_tag_value	string Incidents with the given custom tag value.
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

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

Internal Secret Occurrences

List secret occurrences

List occurrences of secrets in the monitored perimeter.

Authorizations:

api-key

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.
source_id	integer Example: source_id=5523 Filter on the source ID.
source_name	string Example: source_name=gitguardian/test-repository Entries matching this source name search.
source_type	string Enum: bitbucket bitbucket_cloud github gitlab azure_devops slack jira_cloud confluence_cloud microsoft_teams confluence_data_center jira_data_center aws_ecr azure_cr google_artifact jfrog_artifact docker_hub servicenow sharepoint_online sharepoint_online_drive sharepoint_online_pages microsoft_onedrive custom_source Example: source_type=github Filter by source type.
incident_id	integer Filter by incident ID.
presence	string Enum: present removed Entries that have the following presence status.
author_name	string >= 3 characters Example: author_name=John Doe Entries matching this author name search.
author_info	string >= 3 characters Example: author_info=john.doe@gitguardian.com Entries matching this author email search.
sha	string >= 3 characters Example: sha=fccebf0562698ab99dc10dcb2e864fc563b25ac4 Entries starting with the commit sha search string.
filepath	string >= 3 characters Example: filepath=myfile.txt Entries matching this filepath search.
severity	string Enum: critical high medium low info unknown Example: severity=critical,high Filter occurrences by the severity of their related incident. Can specify multiple values separated by commas.
status	string Enum: IGNORED TRIGGERED ASSIGNED RESOLVED Example: status=TRIGGERED,ASSIGNED Filter occurrences by the status of their related incident. Can specify multiple values separated by commas.
validity	string Enum: valid invalid failed_to_check no_checker unknown Example: validity=valid,invalid Filter occurrences by the validity of their related secret. Can specify multiple values separated by commas.
tags	string Enum: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED NONE Example: tags=FROM_HISTORICAL_SCAN,SENSITIVE_FILE Occurrences with one of the following tags. Use `NONE` if you want to filter occurrences with no tags.
exclude_tags	string Enum: DEFAULT_BRANCH FROM_HISTORICAL_SCAN CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED NONE Example: exclude_tags=TEST_FILE,FALSE_POSITIVE Exclude occurrences with any of the following tags (comma-separated). Use `NONE` to exclude occurrences with no tags.
ordering	string Enum: date -date 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
503

Content type

application/json

[{"id": 4421,
"incident_id": 3759,
"kind": "realtime",
"source": {"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
},
"author_name": "Eric",
"author_info": "eric@gitguardian.com",
"date": "2021-05-20T12:40:55.662949Z",
"url": "https://github.com/prm-dev-team/QATest_staging/commit/76dd18a2a8d27eaf00a45851cc7731c53b59ed19#diff-0f372f3171c8f13a15a22a1081487ed54fa70ad088e17c6c6386196a179a04ffR1",
"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"
}
]

Internal Secret Incident Notes

List notes on a secret incident

List notes left on a secret incident in chronological order.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

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.
ordering	string Enum: created_at -created_at updated_at -updated_at Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
member_id	integer Example: member_id=1 Filter by member id.
search	string Example: search=I revoked this Search notes based on the comment field content.

Responses

Response samples

200
400
401
404
503

Content type

application/json

[{"id": 17,
"incident_id": 42,
"member_id": 38,
"api_token": null,
"api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret",
"issue_id": 42,
"user_id": 38
}
]

Create a secret incident note

Add a note on a secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

comment

required

string <= 10000 characters

Content of the incident note

Responses

Request samples

Payload

Content type

application/json

{"comment": "I revoked this secret"
}

Response samples

201
400
401
404
503

Content type

application/json

{"id": 17,
"incident_id": 42,
"member_id": 38,
"api_token": null,
"api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret",
"issue_id": 42,
"user_id": 38
}

Update a secret incident note

Update an existing comment on a secret incident. Only incident notes created by the current API key can be updated.

Authorizations:

api-key

path Parameters

incident_id required	integer The id of the incident to retrieve
note_id required	integer The id of the incident note to update

Request Body schema: application/json

comment

required

string <= 10000 characters

Content of the incident note

Responses

Request samples

Payload

Content type

application/json

{"comment": "I revoked this secret"
}

Response samples

Content type

application/json

{"id": 17,
"incident_id": 42,
"member_id": 38,
"api_token": null,
"api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret",
"issue_id": 42,
"user_id": 38
}

Delete a secret incident note

Delete an existing comment on a secret incident. Only incident notes created by the current API key can be deleted.

Authorizations:

api-key

path Parameters

incident_id required	integer The id of the incident to retrieve
note_id required	integer The id of the incident note to delete

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Public Secret Incidents

List public secret incidents

List public secret incidents detected by the GitGuardian dashboard.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
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 Public secret incidents assigned to this email.
assignee_id	integer Example: assignee_id=4932 Public secret incidents assigned to this user id.
status	string Enum: IGNORED TRIGGERED ASSIGNED RESOLVED Public secret incidents with the following status.
severity	string Enum: critical high medium low info unknown Filter public secret incidents by severity.
validity	string Enum: valid invalid failed_to_check no_checker unknown Public secret incident with the following validity.
tags	string Enum: SENSITIVE_FILE TEST_FILE MINIFIED_FILE PROD WHITELISTED DECODED_BASE64 DECRYPTED JWT_PROPERTIES COMPANY_DOMAIN COMPANY_NAME_IN_COMMIT FROM_HISTORICAL_SCAN FROM_SECRET_GRASPER FROM_EXPLORE FALSE_POSITIVE IS_COMPANY_CONTEXT INTERNALLY_LEAKED Example: tags=FROM_HISTORICAL_SCAN,INTERNALLY_LEAKED Public secret incidents with one of the following tags. Use `NONE` if you want to filter incidents with no tags.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Public secret incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Public secret incidents with the given custom tag key.
custom_tag_value	string Public secret incidents with the given custom tag value.
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 Public secret incidents belonging to the specified detector group.
ignorer_id	integer Example: ignorer_id=4932 Public secret incidents ignored by this user id.
ignorer_api_token_id	string <uuid> Example: ignorer_api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8 Public secret incidents ignored by this API token id.
resolver_id	integer Example: resolver_id=4932 Public secret incidents resolved by this user id.
resolver_api_token_id	string <uuid> Example: resolver_api_token_id=fdf075f9-1662-4cf1-9171-af50568158a8 Public secret incidents resolved by this API token id.
feedback	boolean Public secret incidents with or without feedback.
declarative_secret_status	string Enum: revoked active test_credential false_positive low_risk Public secret incidents with the following declarative secret status.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}
]

Retrieve a public secret incident

Retrieve public secret incident detected by the GitGuardian dashboard

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
400
401
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Resolve a public secret incident

Resolve a public secret incident detected by the GitGuardian dashboard.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

resolve_reason

required

string

Enum: revoked dmca_request source_deleted

Comma-separated list of reasons for resolving the incident

Responses

Request samples

Payload

Content type

application/json

{"resolve_reason": "revoked"
}

Response samples

200
400
401
409
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Ignore a public secret incident

Ignore a public secret incident detected by the GitGuardian dashboard.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

ignore_reason

required

string

Enum: test_credential false_positive low_risk invalid ignore_actor ignore_secret

Comma-separated list of reasons for ignoring the incident

Responses

Request samples

Payload

Content type

application/json

{"ignore_reason": "test_credential,ignore_actor"
}

Response samples

200
400
401
409
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Reopen a public secret incident

Reopen a public secret incident that was previously resolved or ignored.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
400
401
409
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Assign a public secret incident

Assign a public secret incident to a workspace member by email or member ID.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

send_email

boolean

Default: true

Whether to notify the assignee.

Request Body schema: application/json

email	string email of the member to assign. This parameter is mutually exclusive with `member_id`.
member_id	number id of the member to assign. This parameter is mutually exclusive with `email`.

Responses

Request samples

Payload

Content type

application/json

{"email": "eric@gitguardian.com",
"member_id": 4295
}

Response samples

200
400
401
409
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Unassign a public secret incident

Unassign a public secret incident from its current assignee.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

200
400
401
409
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Unshare a public secret incident

Delete a public secret incident's share link.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Responses

Response samples

400
401
409
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Set severity of a public secret incident

Set the severity of a public secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

severity

required

string

Enum: critical high medium low info

The severity level to set

Responses

Request samples

Payload

Content type

application/json

{"severity": "high"
}

Response samples

200
400
401
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Set custom tags of a public secret incident

Set the custom tags of a public secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

required

Array of objects

List of custom tags to set

Responses

Request samples

Payload

Content type

application/json

{"custom_tags": [{"key": "environment",
"value": "production"
}
]
}

Response samples

200
400
401
503

Content type

application/json

{"id": 3759,
"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"
},
"date": "2019-08-22T14:15:22Z",
"secret_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"occurrences_count": 4,
"status": "IGNORED",
"triggered_at": "2019-05-12T09:37:49Z",
"ignored_at": "2019-08-24T14:15:22Z",
"ignore_reason": "test_credential,ignore_actor",
"ignorer_id": 309,
"ignorer_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"resolved_at": null,
"resolver_id": 395,
"resolver_api_token_id": "fdf075f9-1662-4cf1-9171-af50568158a8",
"secret_revoked": false,
"validity": "valid",
"severity": "high",
"assignee_id": 309,
"assignee_email": "eric@gitguardian.com",
"share_url": "https://dashboard.gitguardian.com/share/public-incidents/11111111-1111-1111-1111-111111111111",
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"declarative_secret_status": "revoked",
"resolve_reason": "revoked",
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/public-incidents/3899",
"tags": ["FROM_HISTORICAL_SCAN",
"INTERNALLY_LEAKED"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
]
}

Public Secret Incident Notes

List notes on a public secret incident

List notes left on a public secret incident in chronological order.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
ordering	string Enum: created_at -created_at updated_at -updated_at Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
member_id	integer Example: member_id=1 Filter by member id.
search	string Example: search=I revoked this Search notes based on the comment field content.

Responses

Response samples

200
400
401
404
503

Content type

application/json

[{"id": 17,
"incident_id": 42,
"member_id": 38,
"api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret"
}
]

Create a public secret incident note

Add a note on a public secret incident.

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

Request Body schema: application/json

comment

required

string <= 10000 characters

Content of the incident note

Responses

Request samples

Payload

Content type

application/json

{"comment": "I revoked this secret"
}

Response samples

201
400
401
404
503

Content type

application/json

{"id": 17,
"incident_id": 42,
"member_id": 38,
"api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret"
}

Update a public secret incident note

Update an existing comment on a public secret incident. Only incident notes created by the current API key can be updated.

Authorizations:

api-key

path Parameters

incident_id required	integer The id of the incident to retrieve
note_id required	integer The id of the incident note to update

Request Body schema: application/json

comment

required

string <= 10000 characters

Content of the incident note

Responses

Request samples

Payload

Content type

application/json

{"comment": "I revoked this secret"
}

Response samples

Content type

application/json

{"id": 17,
"incident_id": 42,
"member_id": 38,
"api_token_id": "3220d951-00ce-446c-ac90-9822f0f9b71e",
"created_at": "2019-08-22T14:15:22Z",
"updated_at": null,
"comment": "I revoked this secret"
}

Delete a public secret incident note

Delete an existing comment on a public secret incident. Only incident notes created by the current API key can be deleted.

Authorizations:

api-key

path Parameters

incident_id required	integer The id of the incident to retrieve
note_id required	integer The id of the incident note to delete

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Public Secret Occurrences

List public secret occurrences

List occurrences of a public secret incident detected by the GitGuardian dashboard

Authorizations:

api-key

path Parameters

incident_id

required

integer

The id of the incident to retrieve

query Parameters

cursor	string Pagination cursor.
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.
source_id	integer Example: source_id=5523 Filter on the source ID.
presence	string Enum: present removed Entries that have the following presence status.
sha	string >= 3 characters Example: sha=fccebf0562 Entries starting with the commit sha search string.
filepath	string >= 3 characters Example: filepath=myfile.txt Entries matching this filepath search.
attachment_reason	string Enum: by_dev_from_perimeter on_github_org_in_perimeter from_secret_grasper Example: attachment_reason=by_dev_from_perimeter,on_github_org_in_perimeter Occurrences with one of the following attachment reasons.
severity	string Enum: critical high medium low info unknown Example: severity=critical,high Filter occurrences by the severity of their related incident. Can specify multiple values separated by commas.
status	string Enum: IGNORED TRIGGERED ASSIGNED RESOLVED Example: status=TRIGGERED,ASSIGNED Filter occurrences by the status of their related incident. Can specify multiple values separated by commas.
validity	string Enum: valid invalid failed_to_check no_checker unknown Example: validity=valid,invalid,no_checker Filter occurrences by the validity of their related secret. Can specify multiple values separated by commas.
tags	string Enum: SENSITIVE_FILE TEST_FILE MINIFIED_FILE PROD WHITELISTED DECODED_BASE64 DECRYPTED JWT_PROPERTIES COMPANY_DOMAIN COMPANY_NAME_IN_COMMIT FROM_HISTORICAL_SCAN FROM_SECRET_GRASPER FROM_EXPLORE FALSE_POSITIVE IS_COMPANY_CONTEXT INTERNALLY_LEAKED Example: tags=FROM_HISTORICAL_SCAN,INTERNALLY_LEAKED Public secret incidents with one of the following tags. Use `NONE` if you want to filter incidents with no tags.
ordering	string Enum: id -id 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 '-'.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"id": 12345,
"incident_id": 3759,
"date": "2019-08-22T14:15:22Z",
"filepath": "src/config/database.yml",
"kind": "realtime",
"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
}
],
"tags": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"sha": "fccebf0562698ab99dc10dcb2e864fc563b25ac4",
"url": "https://github.com/gitguardian/test-repository/blob/main/src/config/database.yml",
"source": {"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
},
"actor": {"id": 12345,
"type": "github_user",
"name": "John Doe",
"email": "john.doe@example.com",
"url": "https://github.com/johndoe"
},
"attachment_reasons": ["by_dev_from_perimeter"
]
}
]

Retrieve a public secret occurrence

Retrieve a specific occurrence of a public secret incident detected by the GitGuardian dashboard

Authorizations:

api-key

path Parameters

incident_id required	integer The id of the incident to retrieve
occurrence_id required	integer Example: 12345 The ID of the occurrence to retrieve

Responses

Response samples

200
400
401
503

Content type

application/json

{"id": 12345,
"incident_id": 3759,
"date": "2019-08-22T14:15:22Z",
"filepath": "src/config/database.yml",
"kind": "realtime",
"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
}
],
"tags": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"sha": "fccebf0562698ab99dc10dcb2e864fc563b25ac4",
"url": "https://github.com/gitguardian/test-repository/blob/main/src/config/database.yml",
"source": {"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
},
"actor": {"id": 12345,
"type": "github_user",
"name": "John Doe",
"email": "john.doe@example.com",
"url": "https://github.com/johndoe"
},
"attachment_reasons": ["by_dev_from_perimeter"
]
}

Status

Check the status of the API and the overall system health.

Health check

Check the status of the API and your token without spending your quota.

Authorizations:

api-key

Responses

Request samples

cURL
Python

curl --request GET \
    --url https://api.gitguardian.com/v1/health \
    --header 'authorization: Token <Insert API Key>'

Response samples

200
401
503

Content type

application/json

{"detail": "Valid API key."
}

Sources

Retrieve details on sources known by GitGuardian.

List sources

List sources known by GitGuardian.

Authorizations:

api-key

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.
search	string Example: search=test-repository Sources matching this search.
last_scan_status	string Enum: pending running canceled failed too_large timeout pending_timeout finished Filter sources based on the status of their latest historical scan.
health	string Enum: safe unknown at_risk Filter sources based on their health status.
type	string Enum: bitbucket bitbucket_cloud github gitlab azure_devops slack jira_cloud confluence_cloud microsoft_teams confluence_data_center jira_data_center aws_ecr azure_cr google_artifact jfrog_artifact docker_hub servicenow sharepoint_online sharepoint_online_drive sharepoint_online_pages microsoft_onedrive custom_source Example: type=github Filter by source type.
ordering	string Enum: last_scan_date -last_scan_date Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
visibility	string Enum: public private internal Example: visibility=public Filter by visibility status.
external_id	string Example: external_id=1 Filter by specific external id.
source_criticality	string Enum: critical high medium low unknown Example: source_criticality=critical Filter by source criticality.
monitored	boolean Example: monitored=true Filter by monitored value.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
}
]

Retrieve a source

Retrieve a source known by GitGuardian.

Authorizations:

api-key

path Parameters

source_id

required

integer

Example: 5523

The id of the source to retrieve.

Responses

Response samples

200
400
401
503

Content type

application/json

{"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
}

Update a source

Update some source attributes such as monitored status and source criticality.

The monitored status can be updated for all source types except Custom Sources.

⚠️ Note: some sources types are supported on this endpoint, but cannot be updated yet on the dashboard.

Business sources can't be updated if your account doesn't have access to them.

Authorizations:

api-key

path Parameters

source_id

required

integer

Example: 5523

The id of the source to retrieve.

Request Body schema: application/json

source_criticality	string Criticality of the source.
monitored	boolean Whether the source is currently monitored by GitGuardian.

Responses

Request samples

Payload

Content type

application/json

{"source_criticality": "critical",
"monitored": true
}

Response samples

200
400
401
503

Content type

application/json

{"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
}

List secret incidents of a source

List secret incidents linked to a source. Occurrences are not returned in this route.

Authorizations:

api-key

path Parameters

source_id

required

integer

Example: 5523

The id of the source to filter on.

query Parameters

cursor	string Pagination cursor.
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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Incidents with the given custom tag key.
custom_tag_value	string Incidents with the given custom tag value.
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.
feedback	boolean Incidents with or without feedback.

Responses

Response samples

200
400
401
503

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

List custom sources

List custom sources for the authenticated account.

⚠️ Beta Version: This endpoint is in beta and may be subject to changes in future releases.

Authorizations:

api-key

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.
search	string Example: search=my-custom-source Custom sources matching this search.
ordering	string Enum: id -id name -name 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
503

Content type

application/json

[{"id": "123",
"source_uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Custom Source",
"description": "A custom source for testing purposes"
}
]

Create custom source

Create a new custom source for the authenticated account.

⚠️ Beta Version: This endpoint is in beta and may be subject to changes in future releases.

Authorizations:

api-key

Request Body schema: application/json

name required	string [ 1 .. 500 ] characters The name of the custom source
description	string or null [ 1 .. 500 ] characters The description of the custom source

Responses

Request samples

Payload

Content type

application/json

{"name": "My Custom Source",
"description": "A custom source for testing purposes"
}

Response samples

201
400
401
403
503

Content type

application/json

{"id": "123",
"source_uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Custom Source",
"description": "A custom source for testing purposes"
}

Get a custom source

Get a custom source by ID.

⚠️ Beta Version: This endpoint is in beta and may be subject to changes in future releases.

Authorizations:

api-key

path Parameters

custom_source_id

required

string

Example: 123

The id of the custom source to retrieve.

Responses

Response samples

200
400
401
404
503

Content type

application/json

{"id": "123",
"source_uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Custom Source",
"description": "A custom source for testing purposes"
}

Update a custom source

Update a custom source's name and description.

⚠️ Beta Version: This endpoint is in beta and may be subject to changes in future releases.

Authorizations:

api-key

path Parameters

custom_source_id

required

string

Example: 123

The id of the custom source to update.

Request Body schema: application/json

name required	string [ 1 .. 500 ] characters The name of the custom source
description	string or null [ 1 .. 500 ] characters The description of the custom source

Responses

Request samples

Payload

Content type

application/json

{"name": "My Custom Source",
"description": "A custom source for testing purposes"
}

Response samples

Content type

application/json

{"id": "123",
"source_uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Custom Source",
"description": "A custom source for testing purposes"
}

Delete a custom source

Delete a custom source. This will also delete the related integration if no other sources exist.

⚠️ Beta Version: This endpoint is in beta and may be subject to changes in future releases.

Authorizations:

api-key

path Parameters

custom_source_id

required

string

Example: 123

The id of the custom source to delete.

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Developer

Retrieve developers from the public perimeter.

List developers

List developers in the public perimeter.

Authorizations:

api-key

query Parameters

search	string Developers matching this search.
ordering	string Enum: github_login -github_login name -name emails -emails is_active -is_active 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
503

Content type

application/json

[{"id": 0,
"type": "github_user",
"avatar_url": "http://example.com",
"emails": ["user@example.com"
],
"first_linked_at": "2019-08-24T14:15:22Z",
"is_active": true,
"github_id": 0,
"github_login": "string",
"name": "string",
"reasons": [{"reason": "github_organization",
"deactivated_at": "2019-08-24T14:15:22Z",
"metadata": { }
}
]
}
]

SCIM Users

System for Cross-domain Identity Management (SCIM) is a standard for automating the exchange of user identity information between identity domains, or IT systems.

Create a member (SCIM)

Create a new workspace member (using SCIM Protocol).

Authorizations:

api-key

Request Body schema: application/scim+json

schemas required	Array of strings Items Value: urn:ietf:params:scim:schemas:core:2.0:User
userName required	string Unique identifier from the IDP Config, this should match the member's email
active required	boolean Whether the User is activated on the application.
required	object
required	Array of objects

Responses

Request samples

Payload

Content type

application/scim+json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "string",
"active": true,
"name": {"familyName": "string",
"givenName": "string"
},
"emails": [{"value": "string",
"primary": false
}
]
}

Response samples

201
400
403
409

Content type

application/scim+json

{"active": true,
"emails": [{"primary": true,
"value": "string"
}
],
"externalId": "string",
"id": "string",
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"name": {"familyName": "string",
"givenName": "string"
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "string"
}

List members (SCIM)

List members of the workspace (using SCIM Protocol).

Authorizations:

api-key

query Parameters

filter	string Examples: filter=userName eq "jdoe" - filter=name.givenName eq "Jane" - filter=name.familyName eq "Doe" - filter=active eq True - filter=externalId eq "jdoe@example.com" - filter=id eq 1234 - Filter users using SCIM filtering DSL.
startIndex	integer >= 1 Default: 1 The 1-based index of the first result in the current set of list results.
count	integer [ 1 .. 100 ] Default: 10 Specifies the desired maximum number of query results per page.

Responses

Response samples

200
400
403

Content type

application/scim+json

{"Resources": [{"active": true,
"emails": [{"primary": true,
"value": "string"
}
],
"externalId": "string",
"id": "string",
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"name": {"familyName": "string",
"givenName": "string"
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "string"
}
],
"itemsPerPage": 0,
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"startIndex": 1,
"totalResults": 0
}

Detail of a member (SCIM)

Detail of a workspace member (using SCIM Protocol).

Authorizations:

api-key

path Parameters

id

required

string

Responses

Response samples

200
403
404

Content type

application/scim+json

{"active": true,
"emails": [{"primary": true,
"value": "string"
}
],
"externalId": "string",
"id": "string",
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"name": {"familyName": "string",
"givenName": "string"
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "string"
}

Update of a member (SCIM)

Update of a workspace member (using SCIM Protocol).

Authorizations:

api-key

path Parameters

id

required

string

Request Body schema: application/scim+json

active required	boolean Whether the User is activated on the application.
userName required	string Unique identifier from the IDP Config, this should match the member's email
required	object
schemas required	Array of strings Items Value: urn:ietf:params:scim:schemas:core:2.0:User

Responses

Request samples

Payload

Content type

application/scim+json

{"active": true,
"userName": "string",
"name": {"familyName": "string",
"givenName": "string"
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
]
}

Response samples

200
400
403
404

Content type

application/scim+json

{"active": true,
"emails": [{"primary": true,
"value": "string"
}
],
"externalId": "string",
"id": "string",
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"name": {"familyName": "string",
"givenName": "string"
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "string"
}

Update (partial) of a member (SCIM)

Update of a workspace member (using SCIM Protocol).

Authorizations:

api-key

path Parameters

id

required

string

Request Body schema: application/scim+json

required	Array of objects See https://www.rfc-editor.org/rfc/rfc7644#section-3.5.2 for more details. Currently, only updating the active status, first name and last name is supported.
schemas required	Array of strings Items Value: urn:ietf:params:scim:api:messages:2.0:PatchOp

Responses

Request samples

Payload

Content type

application/scim+json

{"Operations": [{"op": "replace",
"path": "userName",
"value": true
}
],
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}

Response samples

200
400
403
404

Content type

application/scim+json

{"active": true,
"emails": [{"primary": true,
"value": "string"
}
],
"externalId": "string",
"id": "string",
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"name": {"familyName": "string",
"givenName": "string"
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "string"
}

Delete a member (SCIM)

Delete a workspace member (using SCIM Protocol).

Authorizations:

api-key

path Parameters

id

required

string

Responses

Response samples

400
404

Content type

application/scim+json

{"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"
],
"detail": "string",
"status": "400",
"scimType": "uniqueness"
}

SCIM Groups

System for Cross-domain Identity Management (SCIM) is a standard for automating the exchange of group identity information between identity domains, or IT systems.

List groups (SCIM)

List groups (teams in GIM) of the workspace using the SCIM Protocol.

Authorizations:

api-key

query Parameters

filter	string Examples: filter=id eq "group-123456" - filter=externalId eq "123-456-789" - filter=displayName eq "Developers team" - Filter groups using the SCIM filtering DSL.
startIndex	integer >= 1 Default: 1 The 1-based index of the first result in the current set of list results.
count	integer [ 1 .. 100 ] Default: 10 Specifies the desired maximum number of query results per page.

Responses

Response samples

200
400
403

Content type

application/scim+json

{"Resources": [{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"id": "group-123456",
"externalId": "123-456-789",
"displayName": "Developers team",
"description": "Team grouping all my developers.",
"members": [{"value": "123456",
"ref": "https://api.gitguardian.com/v1/scim/v2/Users/123456",
"type": "User"
}
]
}
],
"itemsPerPage": 0,
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"startIndex": 1,
"totalResults": 0
}

Detail of a group (SCIM)

Detail of a group (team in GIM) using the SCIM Protocol.

Authorizations:

api-key

path Parameters

id

required

string

The identifier of the group. To comply with the SCIM unique identifier rule we use the team ID prefixed by 'group-'. e.g 'group-123456'

Responses

Response samples

200
403
404

Content type

application/scim+json

{"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {"created": "2019-08-24T14:15:22Z",
"lastModified": "2019-08-24T14:15:22Z",
"location": "string",
"resourceType": "ResourceType"
},
"id": "group-123456",
"externalId": "123-456-789",
"displayName": "Developers team",
"description": "Team grouping all my developers.",
"members": [{"value": "123456",
"ref": "https://api.gitguardian.com/v1/scim/v2/Users/123456",
"type": "User"
}
]
}

SCIM Metadata

System for Cross-domain Identity Management (SCIM) is a standard for automating the exchange of user identity information between identity domains, or IT systems.

Service Provider Configuration (SCIM)

List the SCIM specification features available on a service provider.

Authorizations:

api-key

Responses

Response samples

200
403

Content type

application/scim+json

{"bulk": {"maxOperations": 0,
"maxPayloadSize": 0,
"supported": true
},
"changePassword": {"supported": true
},
"etag": {"supported": true
},
"filter": {"maxResults": 0,
"supported": true
},
"meta": {"location": "string",
"resourceType": "ResourceType"
},
"patch": {"supported": true
},
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
],
"sort": {"supported": true
},
"authenticationSchemes": [{"description": "string",
"name": "string",
"primary": true,
"type": "oauth"
}
]
}

List Resource Types (SCIM)

List of Resource Types

Authorizations:

api-key

Responses

Response samples

200
403

Content type

application/scim+json

{"Resources": [{"description": "string",
"endpoint": "string",
"id": "string",
"meta": {"location": "string",
"resourceType": "ResourceType"
},
"name": "string",
"schema": "string",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"
]
}
],
"itemsPerPage": 0,
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}

Resource Types (SCIM)

Detail of a Resource Types

Authorizations:

api-key

path Parameters

name

required

string

Responses

Response samples

200
403
404

Content type

application/scim+json

{"description": "string",
"endpoint": "string",
"id": "string",
"meta": {"location": "string",
"resourceType": "ResourceType"
},
"name": "string",
"schema": "string",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"
]
}

List Schemas (SCIM)

List of SCIM Schemas

Authorizations:

api-key

Responses

Response samples

200
403

Content type

application/scim+json

{"Resources": [{"attributes": [{"caseExact": true,
"description": "string",
"multiValued": true,
"mutability": "readOnly",
"name": "string",
"required": true,
"returned": "always",
"type": "binary",
"uniqueness": "none"
}
],
"description": "string",
"id": "string",
"meta": {"location": "string",
"resourceType": "ResourceType"
},
"name": "string",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"
]
}
],
"itemsPerPage": 0,
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}

Schema (SCIM)

Detail of a Schema

Authorizations:

api-key

path Parameters

name

required

string

Responses

Response samples

200
403
404

Content type

application/scim+json

{"attributes": [{"caseExact": true,
"description": "string",
"multiValued": true,
"mutability": "readOnly",
"name": "string",
"required": true,
"returned": "always",
"type": "binary",
"uniqueness": "none"
}
],
"description": "string",
"id": "string",
"meta": {"location": "string",
"resourceType": "ResourceType"
},
"name": "string",
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"
]
}

Scan Methods

Use GitGuardian's brain at your leisure.

Scanning API allows you to scan any content you want using GitGuardian's secrets detection algorithms.

Content scan

Scan provided document content for policy breaks.

Request body shouldn't exceed 1MB.

This endpoint is stateless and as such will not store in our servers neither the documents nor the secrets found.

Authorizations:

api-key

Request Body schema: application/json

filename	string <= 256 characters
document required	string

Responses

Request samples

Payload
cURL
Python

Content type

application/json

{"filename": ".env",
"document": "\nimport urllib.request\nurl = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'\nresponse = urllib.request.urlopen(url)\nconsume(response.read())\n"
}

Response samples

200
400
401
403
503

Content type

application/json

{"policy_break_count": 2,
"policies": ["Filename",
"File extensions",
"Secrets detection"
],
"policy_breaks": [{"type": ".env",
"policy": "Filenames",
"matches": [{"type": "filename",
"match": ".env"
}
]
},
{"type": "Basic Auth String",
"policy": "Secrets detection",
"validity": "cannot_check",
"matches": [{"type": "username",
"match": "jen_barber",
"index_start": 52,
"index_end": 61,
"line_start": 2,
"line_end": 2
},
{"type": "password",
"match": "correcthorsebatterystaple",
"index_start": 63,
"index_end": 87,
"line_start": 2,
"line_end": 2
},
{"type": "host",
"match": "cake.gitguardian.com",
"index_start": 89,
"index_end": 108,
"line_start": 2,
"line_end": 2
}
]
}
]
}

Multiple content scan

Scan provided document contents for policy breaks. Multiple documents are returned by the same index order.

There should not be more than 20 documents in the payload. Individual documents should not exceed 1MB.

Quota usage is based on requests and not on the content size. One request to this endpoint will consume 1 API call. Also note that the quota is set on a rolling month and not on a calendar month. See this documentation for more details.

This endpoint is stateless and as such will not store in our servers neither the documents nor the secrets found.

Authorizations:

api-key

Request Body schema: application/json

Array (non-empty)

filename	string <= 256 characters
document required	string

Responses

Request samples

Payload
cURL
Python

Content type

application/json

[{"filename": ".env",
"document": "import urllib.request\nurl = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'\nresponse = urllib.request.urlopen(url)\nconsume(response.read())\n"
},
{"filename": "tasks.py",
"document": "__version__=\"1.0.0\""
}
]

Response samples

200
400
401
403
503

Content type

application/json

[{"policy_break_count": 2,
"policies": ["Filename",
"File extensions",
"Secrets detection"
],
"policy_breaks": [{"type": ".env",
"policy": "Filenames",
"matches": [{"type": "filename",
"match": ".env"
}
]
},
{"type": "Basic Auth String",
"policy": "Secrets detection",
"validity": "cannot_check",
"matches": [{"type": "username",
"match": "jen_barber",
"index_start": 52,
"index_end": 61,
"line_start": 2,
"line_end": 2
},
{"type": "password",
"match": "correcthorsebatterystaple",
"index_start": 63,
"index_end": 87,
"line_start": 2,
"line_end": 2
},
{"type": "host",
"match": "cake.gitguardian.com",
"index_start": 89,
"index_end": 108,
"line_start": 2,
"line_end": 2
}
]
}
]
},
{"policy_break_count": 0,
"policies": ["Filename",
"File extensions",
"Secrets detection"
],
"policy_breaks": [ ]
}
]

Scan content and create incidents

Scan provided content for hardcoded secrets and create incidents that will be reflected on the GitGuardian dashboard.

⚠️ Beta Version: This endpoint is in beta and may be subject to changes in future releases.

This endpoint will:

Scan the provided content for hardcoded secrets
Create incidents for any detected secrets
Store the incidents in the GitGuardian dashboard for tracking and management
Return the scan results

Request body shouldn't exceed 1MB.

Authorizations:

api-key

Request Body schema: application/json

source_uuid required	string Unique identifier for the custom source
required	Array of objects non-empty Array of documents to be processed

Responses

Request samples

Payload
cURL

Content type

application/json

{"source_uuid": "550e8400-e29b-41d4-a716-446655440000",
"documents": [{"filename": "document.txt",
"document": ""
}
]
}

Response samples

200
400
401
403
503

Content type

application/json

{"policy_break_count": 2,
"policies": ["Filename",
"File extensions",
"Secrets detection"
],
"policy_breaks": [{"type": ".env",
"policy": "Filenames",
"matches": [{"type": "filename",
"match": ".env"
}
]
},
{"type": "Basic Auth String",
"policy": "Secrets detection",
"validity": "cannot_check",
"matches": [{"type": "username",
"match": "jen_barber",
"index_start": 52,
"index_end": 61,
"line_start": 2,
"line_end": 2
},
{"type": "password",
"match": "correcthorsebatterystaple",
"index_start": 63,
"index_end": 87,
"line_start": 2,
"line_end": 2
},
{"type": "host",
"match": "cake.gitguardian.com",
"index_start": 89,
"index_end": 108,
"line_start": 2,
"line_end": 2
}
]
}
],
"created_incidents": [{"incident_id": 12345,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/12345",
"status": "TRIGGERED",
"severity": "high"
}
]
}

Secret Detectors

Retrieve details on detectors used for secret detection.

List secret detectors

List secret detectors.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
is_active	boolean Example: is_active=true Filter only active or inactive detectors.
type	string Enum: specific generic custom Example: type=generic Filter detectors on their type.
search	string Example: search=aws
ordering	string Enum: name -name 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
403
503

Content type

application/json

[{"name": "aws_iam",
"display_name": "AWS Keys",
"type": "specific",
"category": "Cloud Provider",
"is_active": true,
"scans_code_only": false,
"checkable": true,
"use_with_validity_check_disabled": true,
"frequency": "1O3.74",
"removed_at": null,
"open_incidents_count": 17,
"ignored_incidents_count": 9,
"resolved_incidents_count": 42
}
]

Get a secret detector

Get a secret detector.

Authorizations:

api-key

path Parameters

detector_name

required

string

Example: aws_iam

Name of the detector to retrieve

Responses

Response samples

200
401
403
404
503

Content type

application/json

{"name": "aws_iam",
"display_name": "AWS Keys",
"type": "specific",
"category": "Cloud Provider",
"is_active": true,
"scans_code_only": false,
"checkable": true,
"use_with_validity_check_disabled": true,
"frequency": "1O3.74",
"removed_at": null,
"open_incidents_count": 17,
"ignored_incidents_count": 9,
"resolved_incidents_count": 42
}

Quota

Retrieve details about quota usage.

Quota overview

Check available scanning calls for this token. Quota is shared between all tokens of a workspace

Authorizations:

api-key

Responses

Response samples

200
401
503

Content type

application/json

{"content": {"count": 2,
"limit": 5000,
"remaining": 4998,
"since": "2021-04-18"
}
}

Teams

Manage teams.

List teams

This endpoint allows you to list all the teams of your workspace.

The response contains the list of teams and a pagination cursor to retrieve the next page.

The teams are sorted by id.

If you are using a personal access token, you need to have an access level superior or equal to member.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
is_global	boolean Filter on/exclude the "All-incidents" team.
search	string Search teams based on their name and/or description.
linked_to_an_external_provider	boolean Filter on/exclude teams that are linked to an external provider.

Responses

Response samples

200
400
401
403
503

Content type

application/json

[{"id": 3252,
"name": "feature team A",
"description": "Description of my team",
"is_global": false,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/settings/user/teams/1",
"external_provider_id": "123-456-7890"
}
]

Create a team

This endpoint allows you to create a team.

If you are using a personal access token, you need to have an access level superior or equal to manager.

If a personal access token is being used, the member is automatically added to the created team with permissions can_manage and full_access

Authorizations:

api-key

Request Body schema: application/json

name required	string
description	string or null team description.
external_provider_id	string or null ID of the external provider associated to the team.

Responses

Request samples

Payload

Content type

application/json

{"name": "feature team A",
"description": "Description of my team",
"external_provider_id": "123-456-7890"
}

Response samples

Content type

application/json

{"id": 3252,
"name": "feature team A",
"description": "Description of my team",
"is_global": false,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/settings/user/teams/1",
"external_provider_id": "123-456-7890"
}

Retrieve a team

Retrieve an existing team.

If you are using a personal access token, you need to have an access level greater or equal to member.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

Responses

Response samples

Content type

application/json

{"id": 3252,
"name": "feature team A",
"description": "Description of my team",
"is_global": false,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/settings/user/teams/1",
"external_provider_id": "123-456-7890"
}

Delete a team

Delete an existing team.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

The "All-incidents" team (is_global=true) cannot be deleted.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Update a team

Update a team's name and/or its description.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

The "All-incidents" team (is_global=true) cannot be updated.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

Request Body schema: application/json

name	string
description	string or null team description.
external_provider_id	string or null ID of the external provider associated to the team.

Responses

Request samples

Payload

Content type

application/json

{"name": "feature team A",
"description": "Description of my team",
"external_provider_id": "123-456-7890"
}

Response samples

200
400
401
503

Content type

application/json

{"id": 3252,
"name": "feature team A",
"description": "Description of my team",
"is_global": false,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/settings/user/teams/1",
"external_provider_id": "123-456-7890"
}

List secret incidents of a team Deprecated

List secret incidents of a particular team. Occurrences are not returned in this route.

DEPRECATED: THis endpoint has been replaced by /v1/teams/{team_id}/secret-incidents

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

cursor	string Pagination cursor.
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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Incidents with the given custom tag key.
custom_tag_value	string Incidents with the given custom tag value.
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

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

Check team permission for a resource

Return the permission a team has on a resource.

For the global team, it will always be the highest possible permission.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Responses

Response samples

200
401
403
404
503

Content type

application/json

{"team_id": 1345,
"resource_id": 3252,
"resource_type": "secret-incidents",
"permission": "can_edit"
}

Give a team access to a resource

This will create or update a direct access for the team on the resource. If the access to the resource is already given by the team's perimeter, an error is raised.

This endpoint is not allowed for the global team.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

query Parameters

send_email

boolean

Default: true

Whether to notify the team members about the access.

Request Body schema: application/json
required

permission

string

Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"permission": "can_edit"
}

Response samples

Content type

application/json

{"team_id": 1345,
"resource_id": 3252,
"resource_type": "secret-incidents",
"permission": "can_edit"
}

Revoke a team's access to a resource

Revoke the access a team has to a resource.

This only works for direct accesses. If the access to the resource is given by the team's perimeter, an error is raised.

This endpoint is not allowed for the global team.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Request Body schema: application/json
required

permission

string

Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"permission": "can_edit"
}

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

List secret incidents a team has access to

List secret incidents that a team has access to.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
custom_tags	string Example: custom_tags=d45a123f-b15d-4fea-abf6-ff2a8479de5b,55b349d7-8c3a-40c9-957c-e58f5c3a7391 Incidents with one of the following custom tag ids. To retrieve incidents containing several custom tags at once, this query parameter should be used several times to intersect the results.
custom_tag_key	string Incidents with the given custom tag key.
custom_tag_value	string Incidents with the given custom tag value.
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.
feedback	boolean Incidents with or without feedback.

Responses

Response samples

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

Team Invitations

Manage team invitations.

List team invitations

List all existing team invitations.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
invitation_id	integer The id of an invitation to filter on
is_team_leader	boolean Example: is_team_leader=true Filter team invitations that will become team leaders
team_permission	string Deprecated Enum: can_manage cannot_manage Example: team_permission=can_manage Filter team invitations with a specific team permission team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access Example: incident_permission=can_edit Filter team invitations with a specific incident permission

Responses

Response samples

Content type

application/json

[{"id": 3252,
"invitation_id": 4851,
"team_id": 991,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}
]

Create a team invitation

This endpoint allows you to create a team invitation from an existing team and invitation.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

Request Body schema: application/json

invitation_id required	integer
is_team_leader	boolean
team_permission	string Deprecated Enum: can_manage cannot_manage team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"invitation_id": 4851,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

Response samples

Content type

application/json

{"id": 3252,
"invitation_id": 4851,
"team_id": 991,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

Update a team invitation

Update permissions of a team invitation.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
team_invitation_id required	integer The id of the team invitation

Request Body schema: application/json

is_team_leader	boolean
team_permission	string Deprecated Enum: can_manage cannot_manage team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_view"
}

Response samples

Content type

application/json

{"id": 3252,
"invitation_id": 4851,
"team_id": 991,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

Delete a team invitation

Delete an existing team invitation.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
team_invitation_id required	integer The id of the team invitation

Responses

Response samples

401
403
404
503

Content type

application/json

{"detail": "Invalid API key."
}

Team Memberships

Add or remove members from teams, or update their permissions.

List team memberships

List all the memberships of a team.

If you are using a personal access token, you need to be a workspace manager or be part of the team.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
is_team_leader	boolean Example: is_team_leader=true Filter team memberships that are team leaders
team_permission	string Deprecated Enum: can_manage cannot_manage Example: team_permission=can_manage Filter team memberships with a specific team permission team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access Example: incident_permission=can_edit Filter team memberships with a specific incident permission
member_id	number Example: member_id=1234 Filter team memberships on a specific member

Responses

Response samples

Content type

application/json

[{"id": 1234,
"member_id": 2489,
"team_id": 4285,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}
]

Add a member to a team

Add a member to a team.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the team membership.

Request Body schema: application/json

member_id	integer Id of a workspace member.
is_team_leader	boolean
team_permission	string Deprecated Enum: can_manage cannot_manage team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"member_id": 2489,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

Response samples

Content type

application/json

{"id": 1234,
"member_id": 2489,
"team_id": 4285,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

Update a team membership

Update permissions of a team membership.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
team_membership_id required	integer The id of the team membership

Request Body schema: application/json

is_team_leader	boolean
team_permission	string Deprecated Enum: can_manage cannot_manage team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_view"
}

Response samples

Content type

application/json

{"id": 1234,
"member_id": 2489,
"team_id": 4285,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

Remove a member from a team

Remove a member from a team.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager, or be the member being removed.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
team_membership_id required	integer The id of the team membership

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the removal from the team.

Responses

Response samples

401
403
404
503

Content type

application/json

{"detail": "Invalid API key."
}

Team Requests

List team requests of a team

List pending requests of a team.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
member_id	number Example: member_id=1234 Filter requests coming from a specific member

Responses

Response samples

Content type

application/json

[{"id": 1234,
"member_id": 2489,
"team_id": 4285
}
]

Request access to a team

Create an access request to a team.

You must be authenticated via a Personal Access Token. You must not already have a pending request on the team, be a member of the team, be a workspace manager or have the restricted access level.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

Responses

Response samples

Content type

application/json

{"id": 1234,
"member_id": 2489,
"team_id": 4285
}

Cancel or decline a team request

Cancel or decline a team request.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager, or be the member who created the request being cancelled.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
team_request_id required	integer The id of the team request

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the request having been denied.

Responses

Response samples

401
403
404
503

Content type

application/json

{"detail": "Invalid API key."
}

Accept a team request

Accept a team request by adding the member to the team.

If you are using a personal access token, you must have "can manage" permission on the team or be a workspace manager.

Authorizations:

api-key

path Parameters

team_id required	integer The id of the team
team_request_id required	integer The id of the team request

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the request having been accepted.

Request Body schema: application/json

is_team_leader	boolean
team_permission	string Deprecated Enum: can_manage cannot_manage team_permission is replaced by is_team_leader
incident_permission	string Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_view"
}

Response samples

Content type

application/json

{"id": 1234,
"member_id": 2489,
"team_id": 4285,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}

List team requests of a member

List pending team requests of a member.

If you are using a personal access token, you need to be either a workspace manager or the member being queried.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
team_id	number Example: team_id=1234 Filter requests to a specific team

Responses

Response samples

Content type

application/json

[{"id": 1234,
"member_id": 2489,
"team_id": 4285
}
]

Team Sources

List team sources

List sources belonging to a team's perimeter.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Example: search=test-repository Sources matching this search.
last_scan_status	string Enum: pending running canceled failed too_large timeout pending_timeout finished Filter sources based on the status of their latest historical scan.
health	string Enum: safe unknown at_risk Filter sources based on their health status.
type	string Enum: azure_devops bitbucket bitbucket_cloud github gitlab Example: type=github Filter by integration type.
ordering	string Enum: last_scan_date -last_scan_date Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'.
visibility	string Enum: public private internal Example: visibility=public Filter by visibility status.
external_id	string Example: external_id=1 Filter by specific external id.

Responses

Response samples

Content type

application/json

[{"id": 6531,
"url": "https://github.com/GitGuardian/gg-shield",
"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,
"secret_incidents_breakdown": {"open_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
},
"closed_secret_incidents": {"total": 0,
"severity_breakdown": {"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0,
"unknown": 0
}
}
},
"visibility": "public",
"external_id": "125",
"source_criticality": "critical",
"last_scan": {"date": "2021-05-20T12:40:55.662949Z",
"status": "finished",
"failing_reason": "DMCA takedown",
"commits_scanned": 123,
"branches_scanned": 2,
"duration": "1:30.454444"
},
"monitored": true,
"deleted": true
}
]

Update a team perimeter

This endpoint allows you to add and remove sources from the perimeter of a team.

If you are using a personal access token, you need to be a workspace manager.

Authorizations:

api-key

path Parameters

team_id

required

integer

The id of the team

Request Body schema: application/json

sources_to_add	Array of integers Ids of sources to add to the perimeter.
sources_to_remove	Array of integers Ids of sources to remove from the perimeter.

Responses

Request samples

Payload

Content type

application/json

{"sources_to_add": [0
],
"sources_to_remove": [0
]
}

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

API Tokens

Manage API tokens.

Retrieve details of the current API token.

Authorizations:

api-key

Responses

Response samples

200
401

Content type

application/json

{"id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
"name": "myTokenName",
"workspace_id": 42,
"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 the current API token.

Authorizations:

api-key

Responses

Response samples

401

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

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 ip_allowlist:read ip_allowlist:write sources:read sources:write nhi:send-inventory nhi:write-vault 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

Content type

application/json

[{"id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
"name": "myTokenName",
"workspace_id": 42,
"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-key

path Parameters

token_id

required

string

Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

200
401
404

Content type

application/json

{"id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
"name": "myTokenName",
"workspace_id": 42,
"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-key

path Parameters

token_id

required

string

Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

401
404

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

Payload

Content type

application/json

{"audience": "https://api.hasmysecretleaked.com",
"audience_type": "hmsl"
}

Response samples

200
400
401

Content type

application/json

{"token": "eyJhbGciOiJS[...]"
}

Members

Retrieve details about workspace members.

List members

List members of the workspace.

Authorizations:

api-key

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.
role	string Deprecated Enum: owner manager member restricted Filter members based on their access level. Use `access_level` instead.
access_level	string Enum: owner manager member restricted Filter members based on their access level.
active	boolean Filter members based on their active status.
search	string Search members based on their name or email.
ordering	string Enum: created_at -created_at last_login -last_login 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
503

Content type

application/json

[{"id": 3252,
"name": "John Smith",
"email": "john.smith@example.org",
"role": "owner",
"access_level": "owner",
"active": true,
"created_at": "2023-06-28T16:40:26.897Z",
"last_login": "2023-06-28T16:40:26.897Z"
}
]

Retrieve a member

Retrieve an existing workspace member.

If you are using a personal access token, you need to have an access level greater or equal to member.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

Responses

Response samples

Content type

application/json

{"id": 3252,
"name": "John Smith",
"email": "john.smith@example.org",
"role": "owner",
"access_level": "owner",
"active": true,
"created_at": "2023-06-28T16:40:26.897Z",
"last_login": "2023-06-28T16:40:26.897Z"
}

Delete a member

Delete an existing workspace member.

If you are using a personal access token, you need to have an access level greater or equal to manager.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the removal.

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Update a member

Update an existing workspace member.

If you are using a personal access token, you need to have an access level greater or equal to manager.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the update.

Request Body schema: application/json

role	string Deprecated Enum: owner manager member restricted
access_level	string Enum: owner manager member restricted
active	boolean Whether this member is activated on the workspace.

Responses

Request samples

Payload

Content type

application/json

{"role": "owner",
"access_level": "owner",
"active": true
}

Response samples

Content type

application/json

{"id": 3252,
"name": "John Smith",
"email": "john.smith@example.org",
"role": "owner",
"access_level": "owner",
"active": true,
"created_at": "2023-06-28T16:40:26.897Z",
"last_login": "2023-06-28T16:40:26.897Z"
}

List teams of a member

List teams of a workspace member. The response contains the list of teams and a pagination cursor to retrieve the next page.

The teams are sorted by id.

If you are using a personal access token, you need to have an access level superior or equal to manager except if the requested member is yourself.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Search teams based on their name and/or description.
is_global	boolean Filter on/exclude the "All-incidents" team.

Responses

Response samples

Content type

application/json

[{"id": 3252,
"name": "feature team A",
"description": "Description of my team",
"is_global": false,
"gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/settings/user/teams/1",
"external_provider_id": "123-456-7890"
}
]

Check member permission for a resource

Return the permission a member has on a resource.

The permission is the higher value between the different accesses the member can have (direct access, member's teams accesses, and administrator access).

Authorizations:

api-key

path Parameters

member_id required	integer The id of the workspace member
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Responses

Response samples

200
401
403
404
503

Content type

application/json

{"member_id": 1345,
"resource_id": 3252,
"resource_type": "secret-incidents",
"permission": "can_edit"
}

Give a member access to a resource

This will create or update a direct access for the member on the resource.

If the member has higher permission from another source, they will take precedence over those you have given.

Authorizations:

api-key

path Parameters

member_id required	integer The id of the workspace member
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the access.

Request Body schema: application/json
required

permission

string

Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"permission": "can_edit"
}

Response samples

Content type

application/json

{"member_id": 1345,
"resource_id": 3252,
"resource_type": "secret-incidents",
"permission": "can_edit"
}

Revoke a member's access to a resource

Revoke a member access to a resource.

This only works for direct accesses. If the member has only indirect access, a 404 is returned.

Authorizations:

api-key

path Parameters

member_id required	integer The id of the workspace member
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Request Body schema: application/json
required

permission

string

Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"permission": "can_edit"
}

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

List secret incidents a member has access to

List secret incidents that a member has access to.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
feedback	boolean Incidents with or without feedback.

Responses

Response samples

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

Retrieve a member's email settings

If you are using a personal access token, you need to have access level greater than member to view other member's settings

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

Responses

Response samples

Content type

application/json

{"private_issue_realtime": {"is_active": true,
"settings": {"vcs_author_only": true,
"issue_type": "all_issues"
}
},
"weekly_recap": {"is_active": true,
"settings": { }
},
"private_issue_access": {"is_active": true,
"settings": { }
},
"private_issue_feedback_submitted": {"is_active": true,
"settings": { }
},
"private_issue_ignored_with_valid_secret": {"is_active": true,
"settings": { }
},
"health_checks": {"is_active": true,
"settings": { }
},
"team_updates": {"is_active": true,
"settings": { }
},
"historical_scan_completion": {"is_active": true,
"settings": { }
}
}

Update a member's email settings

If you are using a personal access token, you need to have access level greater than member to edit other member's settings

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

query Parameters

send_email

boolean

Default: true

Whether to notify the member about the update.

Request Body schema: application/json

	object
	object
	object
	object
	object
	object
	object
	object

Responses

Request samples

Payload

Content type

application/json

{"private_issue_realtime": {"is_active": true,
"settings": {"vcs_author_only": true,
"issue_type": "all_issues"
}
},
"weekly_recap": {"is_active": true,
"settings": { }
},
"private_issue_access": {"is_active": true,
"settings": { }
},
"private_issue_feedback_submitted": {"is_active": true,
"settings": { }
},
"private_issue_ignored_with_valid_secret": {"is_active": true,
"settings": { }
},
"health_checks": {"is_active": true,
"settings": { }
},
"team_updates": {"is_active": true,
"settings": { }
},
"historical_scan_completion": {"is_active": true,
"settings": { }
}
}

Response samples

Content type

application/json

{"private_issue_realtime": {"is_active": true,
"settings": {"vcs_author_only": true,
"issue_type": "all_issues"
}
},
"weekly_recap": {"is_active": true,
"settings": { }
},
"private_issue_access": {"is_active": true,
"settings": { }
},
"private_issue_feedback_submitted": {"is_active": true,
"settings": { }
},
"private_issue_ignored_with_valid_secret": {"is_active": true,
"settings": { }
},
"health_checks": {"is_active": true,
"settings": { }
},
"team_updates": {"is_active": true,
"settings": { }
},
"historical_scan_completion": {"is_active": true,
"settings": { }
}
}

List team memberships of a member

List team memberships of a workspace member. The response contains the list of team memberships and a pagination cursor to retrieve the next page.

The team memberships are sorted by id.

If you are using a personal access token, you need to have an access level superior or equal to manager except if the requested member is yourself.

Authorizations:

api-key

path Parameters

member_id

required

integer

The id of the workspace member

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
team_id	integer The id of a team to filter on

Responses

Response samples

Content type

application/json

[{"id": 1234,
"member_id": 2489,
"team_id": 4285,
"is_team_leader": false,
"team_permission": "cannot_manage",
"incident_permission": "can_edit"
}
]

Invitations

Manage workspace invitations.

List invitations

This endpoint allows you to list all pending invitations.

The response contains the list of invitations and a pagination cursor to retrieve the next page.

The invitations are sorted by id.

If you are using a personal access token, you need to have an access level superior or equal to member.

Authorizations:

api-key

query Parameters

cursor	string Pagination cursor.
per_page	integer [ 1 .. 100 ] Default: 20 Number of items to list per page.
search	string Search invitations based on the email field.
ordering	string Enum: date -date 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
403
503

Content type

application/json

[{"id": 3252,
"email": "john.smith@example.org",
"role": "manager",
"access_level": "manager",
"date": "2019-08-22T14:15:22Z"
}
]

Create an invitation

This endpoint allows you to send an invitation to a user.

If you are using a personal access token, you need to have an access level superior or equal to member.

Authorizations:

api-key

query Parameters

send_email

boolean

Whether to send an email to the invitee with a link to accept the invitation.

Request Body schema: application/json

email required	string email of the user to invite.
role	string Deprecated Default: member Enum: manager member restricted Use `access_level` instead.
access_level	string Default: member Enum: manager member restricted

Responses

Request samples

Payload

Content type

application/json

{"email": "eric@gitguardian.com",
"role": "manager",
"access_level": "manager"
}

Response samples

Content type

application/json

{"id": 3252,
"email": "john.smith@example.org",
"role": "manager",
"access_level": "manager",
"date": "2019-08-22T14:15:22Z"
}

Retrieve an invitation

Retrieve an existing invitation.

If you are using a personal access token, you need to have an access level superior or equal to member.

Authorizations:

api-key

path Parameters

invitation_id

required

integer

The id of the invitation to retrieve

Responses

Response samples

Content type

application/json

{"id": 3252,
"email": "john.smith@example.org",
"role": "manager",
"access_level": "manager",
"date": "2019-08-22T14:15:22Z"
}

Delete an invitation

Delete an existing invitation.

If you are using a personal access token, you need to have an access level superior or equal to manager.

Authorizations:

api-key

path Parameters

invitation_id

required

integer

The id of the invitation to retrieve

Responses

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

Resend an invitation

Resend an existing invitation.

If you are using a personal access token, you need to have an access level superior or equal to manager.

Authorizations:

api-key

path Parameters

invitation_id

required

integer

The id of the invitation to retrieve

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

Content type

application/json

{"detail": "Email sent"
}

Check invitation permission for a resource

Return the permission an invitation has on a resource.

If the invitation has an admin access level, it will be the highest possible value.

Authorizations:

api-key

path Parameters

invitation_id required	integer The id of the invitation to retrieve
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Responses

Response samples

200
401
403
404
503

Content type

application/json

{"invitation_id": 1345,
"resource_id": 3252,
"resource_type": "secret-incidents",
"permission": "can_edit"
}

Give an invitation access to a resource

This will create or update a direct access for the invitation on the resource.

If the invitation has an administrator access level, it will take precedence over the permission you have given.

Authorizations:

api-key

path Parameters

invitation_id required	integer The id of the invitation to retrieve
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Request Body schema: application/json
required

permission

string

Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"permission": "can_edit"
}

Response samples

Content type

application/json

{"invitation_id": 1345,
"resource_id": 3252,
"resource_type": "secret-incidents",
"permission": "can_edit"
}

Revoke an invitation's access to a resource

Revoke an invitation access to a resource.

This only works for direct accesses. If the access is from the administrator access level of the invitation, a 404 is returned.

Authorizations:

api-key

path Parameters

invitation_id required	integer The id of the invitation to retrieve
resource_type required	string Value: secret-incidents The kind of resource of the access
resource_id required	integer The id of the resource of the access

Request Body schema: application/json
required

permission

string

Enum: can_view can_edit full_access

Responses

Request samples

Payload

Content type

application/json

{"permission": "can_edit"
}

Response samples

400
401
403
404
503

Content type

application/json

{"detail": "Invalid data.",
"extra": {"field_1": ["error_message_1",
"error_message_2"
],
"field_2": ["error_message_3",
"error_message_4"
],
"non_field_errors": ["error_message_5",
"error_message_6"
]
}
}

List secret incidents an invitation has access to

List secret incidents that an invitation has access to.

Authorizations:

api-key

path Parameters

invitation_id

required

integer

The id of the invitation to retrieve

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 CHECK_RUN_SKIP_FALSE_POSITIVE CHECK_RUN_SKIP_LOW_RISK CHECK_RUN_SKIP_TEST_CRED PUBLIC PUBLICLY_EXPOSED PUBLICLY_LEAKED REGRESSION SENSITIVE_FILE TEST_FILE FALSE_POSITIVE VAULTED 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.
feedback	boolean Incidents with or without feedback.

Responses

Response samples

Content type

application/json

[{"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_id": 1,
"secret_hash": "Ri9FjVgdOlPnBmujoxP4XPJcbe82BhJXB/SAngijw/juCISuOMgPzYhV28m6OG24",
"hmsl_hash": "05975add34ddc9a38a0fb57c7d3e676ffed57080516fc16bf8d8f14308fedb86",
"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,
"secret_presence": {"files_requiring_code_fix": 1,
"files_pending_merge": 1,
"files_fixed": 1,
"outside_vcs": 1,
"removed_outside_vcs": 0,
"in_vcs": 3,
"removed_in_vcs": 0
},
"ignore_reason": "test_credential",
"triggered_at": "2019-05-12T09:37:49Z",
"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": ["FROM_HISTORICAL_SCAN",
"SENSITIVE_FILE"
],
"custom_tags": [{"id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
"key": "env",
"value": "prod"
}
],
"feedback_list": [{"created_at": "2021-05-20T12:40:55.662949Z",
"updated_at": "2021-05-20T12:40:55.662949Z",
"member_id": 42,
"email": "eric@gitguardian.com",
"answers": [{"type": "boolean",
"field_ref": "actual_secret_yes_no",
"field_label": "Is it an actual secret?",
"boolean": true
}
]
}
],
"occurrences": null
}
]

auto_healing	boolean Default: false Allow the developer to resolve or ignore through the share link
feedback_collection	boolean Default: true Allow the developer to submit their feedback through the share link
lifespan	integer >= 0 Default: 0 Lifespan, in hours, of the share link. If 0 or unset, a default value will be applied based on the workspace settings.

feedback_collection	boolean Default: false Whether to allow feedback collection on the shared incident.
auto_healing	boolean Default: false Whether to allow auto-healing actions on the shared incident.
lifespan	number The lifespan of the share link in hours.

GitGuardian API (1.1.0)

Introduction

Authentication

Pagination

Audit Logs

List audit Logs

Authorizations:

query Parameters

Responses

Response samples

Custom Tags

List custom tags

Authorizations:

query Parameters

Responses

Response samples

Create a custom tag

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update custom tags key

Authorizations:

query Parameters

Responses

Response samples

Delete a custom tags key

Authorizations:

query Parameters

Responses

Response samples

Retrieve a custom tag

Authorizations:

path Parameters

Responses

Response samples

Full Update of a Custom Tag

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Partial update of a Custom Tag

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Deletion of a custom tag

Authorizations:

path Parameters

Responses

Response samples

Honeytokens

List honeytokens

Authorizations:

query Parameters

Responses

Response samples

Create a honeytoken

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Create a honeytoken within a context

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Retrieve a honeytoken

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Request Body schema: application/json
required