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.

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

Content type
application/json
[
  • {
    }
]

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

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

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

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

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

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

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

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

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

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)
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 (customTag)

Custom tags to set on the honeytoken. If the custom tag 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": [
    ],
  • "custom_tags": [
    ]
}

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": [
    ],
  • "custom_tags": [
    ]
}

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": [
    ],
  • "custom_tags": [
    ]
}

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 (customTag)

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

Responses

Request samples

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

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": [
    ],
  • "custom_tags": [
    ]
}

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": [
    ],
  • "custom_tags": [
    ]
}

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": [
    ],
  • "custom_tags": [
    ]
}

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

Content type
application/json
[
  • {
    }
]

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

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

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

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

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

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

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

Response samples

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

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

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

IP Allowlist

Manage the IP allowlist for workspace access.

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "tag": "Main office",
  • "ip_ranges": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "tag": "Main office",
  • "created_at": "2019-08-22T14:15:22Z",
  • "ip_ranges": [
    ]
}

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": [
    ]
}

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

Content type
application/json
{
  • "tag": "Satellite office",
  • "ip_ranges": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
  • "tag": "Main office",
  • "created_at": "2019-08-22T14:15:22Z",
  • "ip_ranges": [
    ]
}

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

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

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.

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.

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": [
    ],
  • "custom_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
Array of objects (customTag)

Responses

Request samples

Content type
application/json
{
  • "severity": "high",
  • "custom_tags": [
    ]
}

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": [
    ],
  • "custom_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": [
    ],
  • "custom_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": [
    ],
  • "custom_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": [
    ],
  • "custom_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": [
    ],
  • "custom_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": [
    ],
  • "custom_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."
}

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 --request GET \
    --url https://api.gitguardian.com/v1/health \
    --header 'authorization: Token <Insert API Key>'

Response samples

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

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.

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

Content type
application/scim+json
{
  • "Resources": [
    ],
  • "itemsPerPage": 0,
  • "schemas": [
    ],
  • "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

Content type
application/scim+json
{
  • "active": true,
  • "emails": [
    ],
  • "externalId": "string",
  • "id": "string",
  • "meta": {
    },
  • "name": {
    },
  • "schemas": [
    ],
  • "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.

schemas
required
Array of strings
Items Value: urn:ietf:params:scim:schemas:core:2.0:User

Responses

Request samples

Content type
application/scim+json
{
  • "active": true,
  • "schemas": [
    ]
}

Response samples

Content type
application/scim+json
{
  • "active": true,
  • "emails": [
    ],
  • "externalId": "string",
  • "id": "string",
  • "meta": {
    },
  • "name": {
    },
  • "schemas": [
    ],
  • "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 is supported.

schemas
required
Array of strings
Items Value: urn:ietf:params:scim:api:messages:2.0:PatchOp

Responses

Request samples

Content type
application/scim+json
{
  • "Operations": [
    ],
  • "schemas": [
    ]
}

Response samples

Content type
application/scim+json
{
  • "active": true,
  • "emails": [
    ],
  • "externalId": "string",
  • "id": "string",
  • "meta": {
    },
  • "name": {
    },
  • "schemas": [
    ],
  • "userName": "string"
}

Delete a member (SCIM)

Delete a workspace member (using SCIM Protocol).

Authorizations:
api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/scim+json
{
  • "schemas": [
    ],
  • "detail": "string",
  • "status": "400"
}

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

Content type
application/scim+json
{
  • "bulk": {
    },
  • "changePassword": {
    },
  • "etag": {
    },
  • "filter": {
    },
  • "meta": {
    },
  • "patch": {
    },
  • "schemas": [
    ],
  • "sort": {
    },
  • "authenticationSchemes": [
    ]
}

List Resource Types (SCIM)

List of Resource Types

Authorizations:
api-key

Responses

Response samples

Content type
application/scim+json
{
  • "Resources": [
    ],
  • "itemsPerPage": 0,
  • "schemas": [
    ]
}

Resource Types (SCIM)

Detail of a Resource Types

Authorizations:
api-key
path Parameters
name
required
string

Responses

Response samples

Content type
application/scim+json
{
  • "description": "string",
  • "endpoint": "string",
  • "id": "string",
  • "meta": {
    },
  • "name": "string",
  • "schema": "string",
  • "schemas": [
    ]
}

List Schemas (SCIM)

List of SCIM Schemas

Authorizations:
api-key

Responses

Response samples

Content type
application/scim+json
{
  • "Resources": [
    ],
  • "itemsPerPage": 0,
  • "schemas": [
    ]
}

Schema (SCIM)

Detail of a Schema

Authorizations:
api-key
path Parameters
name
required
string

Responses

Response samples

Content type
application/scim+json
{
  • "attributes": [
    ],
  • "description": "string",
  • "id": "string",
  • "meta": {
    },
  • "name": "string",
  • "schemas": [
    ]
}

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

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

Content type
application/json
{
  • "policy_break_count": 2,
  • "policies": [
    ],
  • "policy_breaks": [
    ]
}

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

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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

Content type
application/json
[
  • {
    }
]

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

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

Content type
application/json
{
  • "content": {
    }
}

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.

Responses

Response samples

Content type
application/json
[]

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.

Responses

Request samples

Content type
application/json
{
  • "name": "feature team A",
  • "description": "Description of my team"
}

Response samples

Content type
application/json
{}

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

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

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

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.

Responses

Request samples

Content type
application/json
{
  • "name": "feature team A",
  • "description": "Description of my team"
}

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

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

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

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

Content type
application/json
{
  • "permission": "can_edit"
}

Response samples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Content type
application/json
{
  • "sources_to_add": [
    ],
  • "sources_to_remove": [
    ]
}

Response samples

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

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

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

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
required
integer

The id of the resource of the access

Responses

Response samples

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

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

Content type
application/json
{
  • "permission": "can_edit"
}

Response samples

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

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 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 member's email settings

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": {
    },
  • "weekly_recap": {
    },
  • "private_issue_access": {
    },
  • "private_issue_feedback_submitted": {
    },
  • "private_issue_ignored_with_valid_secret": {
    },
  • "health_checks": {
    },
  • "team_updates": {
    },
  • "historical_scan_completion": {
    }
}

Update a member's email 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

Content type
application/json
{
  • "private_issue_realtime": {
    },
  • "weekly_recap": {
    },
  • "private_issue_access": {
    },
  • "private_issue_feedback_submitted": {
    },
  • "private_issue_ignored_with_valid_secret": {
    },
  • "health_checks": {
    },
  • "team_updates": {
    },
  • "historical_scan_completion": {
    }
}

Response samples

Content type
application/json
{
  • "private_issue_realtime": {
    },
  • "weekly_recap": {
    },
  • "private_issue_access": {
    },
  • "private_issue_feedback_submitted": {
    },
  • "private_issue_ignored_with_valid_secret": {
    },
  • "health_checks": {
    },
  • "team_updates": {
    },
  • "historical_scan_completion": {
    }
}

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

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

Content type
application/json
[
  • {
    }
]

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

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

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

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

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

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

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

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

Content type
application/json
{
  • "permission": "can_edit"
}

Response samples

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

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