canonical: https://jentic.com/apis/gitguardian.com/gitguardian # GitGuardian API The GitGuardian API powers automated secret detection and remediation across source code and developer pipelines. Agents can submit content for scanning, list and triage incidents, manage honeytokens, administer teams and members, configure connected sources, and pull audit logs. The API uses an ApiKey scheme and offers both US and EU production hosts to support regional data residency requirements. ## For AI agents Scan code for leaked secrets, triage incidents, deploy honeytokens, and audit access using the GitGuardian secret-detection API. ## Scope Does not handle SAST, dependency scanning, or runtime application protection - use for secret detection, incident management, and honeytoken operations only. ## Capabilities - Scan a single document or batch of documents for leaked secrets via `/v1/scan` and `/v1/multi_scan` - Triage and resolve secret incidents with state transitions on `/v1/incidents/{incident_id}` - List and revoke honeytokens used to detect attacker activity - Inspect remaining scan quota for the authenticated workspace via `/v1/quota` - List supported secret detector definitions via `/v1/secret_detectors` - Manage team and member access for incident response workflows - Pull audit logs for compliance and post-incident review ## Use cases ### CI Pre-Commit Secret Scanning Block secrets before they reach a remote repository by calling `/v1/multi_scan` from a pre-commit or CI step. The endpoint accepts up to 20 documents per request and returns matched detectors with line offsets, so the pipeline can fail fast and surface a precise remediation prompt to the developer. Example prompt: Submit the contents of a staged commit to `/v1/multi_scan` and return the policy_break_count and the offending detector names ### Incident Triage Automation Automate first-line triage on incoming secret incidents. The agent lists open incidents on `/v1/incidents`, applies a rules-engine classification (e.g. test fixtures vs production keys), and posts a state update to `/v1/incidents/{incident_id}` so security engineers see only confirmed exposures. Example prompt: List all incidents with status=triggered, mark any matching the test-fixture rule as ignored via PATCH on `/v1/incidents/{incident_id}` ### Honeytoken Deployment for Threat Detection Plant honeytokens - fake credentials that alert when used - across documentation, code samples, and S3 buckets to catch attackers post-breach. The `/v1/honeytokens` endpoints create, list, and revoke tokens and surface trigger events so SOC teams can treat any hit as high-confidence intrusion. Example prompt: Create an AWS-style honeytoken with name='docs-trap', description='Embedded in public docs', and return the access_key_id pair to plant ### Compliance Audit Reporting Pull audit logs for SOC 2 or ISO 27001 evidence by paginating `/v1/audit_logs` over a date range. Combine with `/v1/members` to map actor IDs to people and build the access review artefact auditors expect, fully driven from API calls instead of dashboard screenshots. Example prompt: Pull audit log entries from the last 7 days with action_type=incident.resolve and return actor_id, target_id, and timestamp ### AI Agent Security Triage Use Jentic to let an AI agent on a security team take a first pass at every new incident. The agent issues an intent like 'list new secret incidents', Jentic resolves the GET `/v1/incidents` call, executes it with the workspace ApiKey held in the vault, and the agent classifies and routes each result. Example prompt: Through Jentic, list all GitGuardian incidents created in the last 24 hours and return id, detector, and source for each ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/scan` | Scan a single document for secrets | | POST | `/v1/multi_scan` | Batch scan up to 20 documents | | GET | `/v1/incidents` | List secret incidents | | GET | `/v1/quota` | Get remaining scan quota | | GET | `/v1/secret_detectors` | List supported secret detectors | | GET | `/v1/health` | Verify API connectivity and credentials | ## Key resources - **Scanning** — Submit single or batch documents for secret detection - **Incidents** — List, fetch, and update secret incidents - **Public Incidents** — Read public-facing incident records - **Honeytokens** — Create, list, and revoke honeytokens - **Members and Teams** — Administer workspace access - **Sources** — Manage connected source repositories - **Audit Logs** — Pull audit trail entries for compliance - **Tokens** — Manage personal access tokens - **Quota** — Inspect remaining scan quota ## Why Jentic - **Setup:** Wiring the GitGuardian API by hand means passing your key as an Authorization Token header on every request to api.gitguardian.com and rotating that key across callers yourself. Through Jentic you install once, import the GitGuardian API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** GitGuardian sends the content to scan in the request body rather than a resource id in the URL path, so scope the agent to the operations it needs, such as scanning for secrets or reading incidents. You choose the allowed operations, so wider ones like multi-scan or quota reads are only available if you include them. - **Credential handling:** Your GitGuardian key is stored once, encrypted, by your own Jentic One instance and injected at execution time, and can be rotated centrally without touching every caller. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'scan code for secrets' or 'list secret incidents', and Jentic returns the matching GitGuardian operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **SonarCloud API** — Static analysis for code quality and security smells alongside secret scanning - **HashiCorp Nomad API** — Workload orchestrator that consumes secrets which GitGuardian protects - **GitLab API** — Source platform that GitGuardian connects to for repository scanning ## FAQ ### What authentication does the GitGuardian API use? GitGuardian uses an ApiKey scheme - a personal access token sent as Authorization: Token . Tokens are scoped at workspace level and can be revoked from the dashboard. Through Jentic the token is stored encrypted in your Jentic One instance and never enters the agent's prompt context. ### Can I scan code for secrets with the GitGuardian API? Yes. POST `/v1/scan` accepts a single document up to 1MB; POST `/v1/multi_scan` accepts up to 20 documents per request. The response lists detected policy breaks with detector name, type, and line offsets so a CI step can fail with a specific remediation message. ### What are the rate limits for the GitGuardian API? Public scan endpoints are limited to 50 requests per minute by default and a daily quota tied to the subscription tier. Call GET `/v1/quota` to inspect the current consumption and remaining count for the authenticated workspace before kicking off a large batch. ### How do I list and resolve incidents through Jentic with GitGuardian? Search Jentic for 'list secret incidents', load GET `/v1/incidents` and PATCH `/v1/incidents/{incident_id}`, and execute against the workspace token in the vault. Pass status=triggered when listing and a resolution payload when updating to close an incident. ### Does the GitGuardian API support EU data residency? Yes. The spec exposes both the US production server at https://api.gitguardian.com and the EU production server at https://api.eu1.gitguardian.com. Pick the host that matches your workspace region; the path and authentication scheme are identical across both. ### How do honeytokens work in the GitGuardian API? Create a honeytoken via POST `/v1/honeytokens` to receive a fake but valid-looking credential pair (for example AWS access key id and secret). Plant the pair anywhere an attacker might scrape; any use of the credential triggers an event you can read via GET `/v1/honeytokens/{id}/events.` ### How can I export GitGuardian audit logs for compliance? Paginate GET `/v1/audit_logs` with a created_at range to retrieve every workspace event, then join actor_id and target_id to GET `/v1/members.` The result is a SOC-2-ready trail showing who resolved or reopened each incident over the audit period. ### Can I limit what my agent is allowed to do with the GitGuardian API? Yes. Because you self-host Jentic One, your own rules decide which GitGuardian operations and credentials the agent may use, so you can allow only what it needs, such as POST `/v1/scan` for single-document scanning or GET `/v1/incidents` for read-only triage. GitGuardian sends the content to scan in the request body rather than a resource id in the URL path, so scoping is done at the operation level rather than per resource. Wider operations like POST `/v1/multi_scan`, GET `/v1/quota`, or the honeytoken and audit-log endpoints are reachable only if you include them in the agent's allowed set. The workspace key is stored once and injected at execution time, never entering the agent's prompt.