GitGuardian
API docs by Redocly

GitGuardian API (1.1.0)

Download OpenAPI specification:Download

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

Introduction

Whether you want to build a complete integration with your software development workflow or simply want to test GitGuardian's policy break detection on any text content, you can use our API.

  • The base url for the latest version is 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:

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.

API Tokens

Manage API tokens.

Retrieve details of the current API token.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  • "name": "myTokenName",
  • "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": [
    ]
}

Revoke the current API token.

Authorizations:
api-key

Responses

Response samples

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

List API tokens.

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

Authorizations:
api-key
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:write
Example: scopes=incidents:read,api_tokens:read

Tokens with one of the following scopes.

search
string

Search tokens based on their name.

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve details of an API token.

Authorizations:
api-key
path Parameters
token_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the token.

Responses

Response samples

Content type
application/json
{
  • "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  • "name": "myTokenName",
  • "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": [
    ]
}

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

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

Create a JSON Web Token.

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

Authorizations:
api-key
Request Body schema: application/json
audience
required
string

Audience of the JWT.

audience_type
string

Type of audience.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Secret Incidents

Manage incidents found by post-receive hooks on your GitGuardian Dashboard.

List secret incidents

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

Authorizations:
api-key
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 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
[
  • {
    }
]

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

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "occurrences": [
    ]
}

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "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

Content type
application/json
[]

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

Content type
application/json
{
  • "email": "eric@gitguardian.com",
  • "member_id": 4295
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "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

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "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

Content type
application/json
{
  • "secret_revoked": true
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "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

Responses

Request samples

Content type
application/json
{
  • "ignore_reason": "low_risk"
}

Response samples

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "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

Content type
application/json
{
  • "id": 3759,
  • "date": "2019-08-22T14:15:22Z",
  • "detector": {
    },
  • "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": {
    },
  • "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": [
    ],
  • "feedback_list": [
    ],
  • "occurrences": null
}

Share a secret incident

Share a secret incident by creating a public link.

Authorizations:
api-key
path Parameters
incident_id
required
integer

The id of the incident to retrieve

Request Body schema: application/json
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.

Responses

Request samples

Content type
application/json
{
  • "auto_healing": true,
  • "feedback_collection": true,
  • "lifespan": 720
}

Response samples

Content type
application/json
{}

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

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

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

Content type
application/json
{
  • "member_id": 1492,
  • "incident_permission": "can_edit"
}

Response samples

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

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

Content type
application/json
{
  • "member_id": 1492
}

Response samples

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

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

Content type
application/json
[
  • {
    }
]

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
[
  • {
    }
]

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
[
  • {
    }
]

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

Content type
application/json
{}

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
[
  • {
    }
]

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
[]

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
[
  • {
    }
]

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 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
[
  • {
    }
]

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 NONE
Example: tags=FROM_HISTORICAL_SCAN,SENSITIVE_FILE

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

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

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

detector_group_name
string
Example: detector_group_name=slackbot_token

Incidents belonging to the specified detector group.

ignorer_id
integer
Example: ignorer_id=4932

Incidents ignored by this user id.

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

Incidents ignored by this API token id.

resolver_id
integer
Example: resolver_id=4932

Incidents resolved by this user id.

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

Incidents resolved by this API token id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Secret Occurrences

Manage occurrences found by post-receive hooks on your GitGuardian Dashboard.

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 servicenow
Example: source_type=github

Filter by integration 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.

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

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

Content type
application/json
[
  • {
    }
]

Secret Incident Notes

Manage notes on incidents found by post-receive hooks on your GitGuardian Dashboard.

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

Content type
application/json
[
  • {
    }
]

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

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
}

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

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

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

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

Content type
application/json
[
  • {
    }
]

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)

Labels to set on the honeytoken. If the label doesn't exist, it will be created.

Responses

Request samples

Content type
application/json
{
  • "name": "honeytoken name",
  • "description": "This honeytoken was placed in the repository test",
  • "type": "AWS",
  • "labels": [
    ]
}

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": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

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

Content type
application/json
{
  • "name": "honeytoken name",
  • "description": "This honeytoken was placed in the repository test",
  • "type": "AWS",
  • "labels": [
    ],
  • "language": "python",
  • "filename": "test_config.py",
  • "project_extensions": [
    ]
}

Response samples

Content type
application/json
{}

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": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

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)

A new set of labels for the honeytoken. Will completely override the former labels.

Responses

Request samples

Content type
application/json
{
  • "name": "test-honeytoken",
  • "description": "honeytoken in repository test",
  • "labels": [
    ]
}

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": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

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

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": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

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

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": {
    },
  • "tags": [
    ],
  • "labels": [
    ]
}

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

Content type
application/json
[]

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "comment": "I revoked this honeytoken"
}

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

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

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

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

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

Content type
application/json
[]

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

List labels created for honeytokens in chronological order.

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

Content type
application/json
[
  • {
    }
]

Create a label

Create a label for honeytokens.

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

Content type
application/json
{
  • "key": "env",
  • "value": "production"
}

Response samples

Content type
application/json
{
  • "id": "0cad1887-d616-4a46-8b5e-4c7b3a70dbaf",
  • "key": "env",
  • "value": "production"
}

Update a key

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

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

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

Delete a key

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

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

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

Update a value

Rename the value of a label.

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

Content type
application/json
{
  • "value": "production"
}

Response samples

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

Delete a label

Delete a label for honeytokens.

Authorizations:
api-key
path Parameters
label_id
required
string
Example: 5ddaad0c-5a0c-4674-beb5-1cd198d13360

Id of the label.

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid 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 servicenow
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.

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

Content type
application/json
[
  • {
    }
]

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

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": {
    },
  • "visibility": "public",
  • "external_id": "125",
  • "source_criticality": "critical",
  • "last_scan": {
    },
  • "monitored": true
}

Update a source

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

Only VCS sources can update the monitored status.

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

Content type
application/json
{
  • "source_criticality": "critical",
  • "monitored": true
}

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": {
    },
  • "visibility": "public",
  • "external_id": "125",
  • "source_criticality": "critical",
  • "last_scan": {
    },
  • "monitored": 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 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
[
  • {
    }
]

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

Content type
application/json
[
  • {
    }
]

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

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

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

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
[]

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