Skip to main content

Introduction

The GitGuardian API gives you full creative control to manage your dashboard data and also to use GitGuardian secrets detection engine, whether through ggshield or in a custom way. All API calls need to be authenticated.

Use cases#

  • Export your incidents to build custom reports.
  • Manage your incidents programmatically.
  • Perform your users and teams management programmatically.
  • Plug GitGuardian easily into your existing services.
  • Build your own integration for secrets detection.
  • You want to use ggshield to shift left.

Scopes#

Scopes are tied to an API key and control the access to resources and scan capability.

Dashboard data management scopes:

  • incidents

    • incidents:share: grant view, edit and share permissions on the incidents of your GitGuardian workspace.
    • incidents:write: grant view and edit permissions on the incidents of your GitGuardian workspace.
    • incidents:read: grant view only permission on the incidents of your GitGuardian workspace.

  • honeytokens

    • honeytokens:write: grant view and edit permissions on the honeytokens of your GitGuardian workspace. Available under specific conditions: the honeytoken module must be enabled for the workspace, and for personal access token the role must be minimum "manager".
    • honeytokens:read: grant view only permission on the honeytokens of your GitGuardian workspace. Available under specific conditions: the honeytoken module must be enabled for the workspace, and for personal access token the role must be minimum "manager".

  • members

    • members:write: grant view and edit permissions on the members of your GitGuardian workspace.
    • members:read: grant view permission on the members of your GitGuardian workspace.

  • teams

    • teams:write: grant view and edit permissions on the teams of your GitGuardian workspace.
    • teams:read: grant view permission on the teams of your GitGuardian workspace.

  • api_tokens

    • api_tokens:write: grant view and edit permissions on the api tokens (personal access tokens and service accounts) of your GitGuardian workspace.
    • api_tokens:read: grant view permission on the api tokens (personal access tokens and service accounts) of your GitGuardian workspace.

  • audit_logs:read: grant view permission on the audit logs of your GitGuardian workspace. If you are using personal access tokens, it is only available to Managers.

Scan capability scope:

  • scan: grant permissions to scan any text content for secrets with GitGuardian secrets detection engine. Required to use ggshield.

You can even test this capability directly in the Secrets detection playground section in your dashboard:

API Secrets detection playground

Considerations#

  • The GitGuardian API is versioned.
  • All requests to the GitGuardian API must be authenticated.
  • The GitGuardian API enforces rate limits on all requests.

Limitations#

  • Only secret incidents are available through the API.

Start to use the API by creating your API key ->