Authentication
The GitGuardian API uses API keys to authenticate requests.
Creating your API key
There are 2 different types of API keys:
- Service accounts: a special type of token intended to represent a non-human user that needs to authenticate and be authorized for scenarios such as secrets scanning in CI pipelines or batch processing open incidents.
- Personal access tokens: a token intended for the use of the GitGuardian API and command-line application ggshield by individual developers on their local workstations (e.g. pre-commit or pre-push git hooks).
You need to create an account in order to get an API key. Your API key must kept private and should neither be embedded directly in the code nor versioned in Git. (Please do not push GitGuardian's API keys to public GitHub repositories ^^).
As in the example below, use the /health
endpoint to check the validity of your API key.
Authentication scheme
The GitGuardian API uses Authorization
header authentication for its requests. The Authorization
header value must be prefixed with Token
.
Example request using curl
:
curl -H "Authorization: Token ${TOKEN}" \
https://api.gitguardian.com/v1/health
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: