Skip to main content

​
Overview

API tokens allow you to access the ZeroPath API programmatically — from CI/CD pipelines, the CLI, the VS Code extension, the MCP server, or custom integrations.

​
Creating Tokens

  1. Navigate to Settings → API Tokens in the ZeroPath dashboard (zeropath.com/app/settings/api).
  2. Click “Create Token”.
  3. Provide a name (optional, for identification).
  4. Set an expiration (1–365 days, default: 30 days).
  5. Click Create.
  6. Copy the Token Secret immediately — it is shown only once and cannot be retrieved later.
You’ll receive two values:
  • Token ID — a UUID identifying the token (safe to log).
  • Token Secret — the secret key (treat like a password).

​
Authentication Headers

Every API request must include both headers: 
X-ZeroPath-API-Token-Id: <your-token-id>
X-ZeroPath-API-Token-Secret: <your-token-secret>

​
Example

curl -X POST https://zeropath.com/api/v2/vulnerabilities/search \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: your-token-id" \
  -H "X-ZeroPath-API-Token-Secret: your-token-secret" \
  -d '{"query": "SQL injection in API endpoints"}'

​
Supported API Surfaces

API tokens authenticate requests to both the V1 and V2 ZeroPath APIs. The V2 API provides expanded coverage including:
  • Vulnerabilities — list, search, and manage security findings, including remediation and patch metadata when available. When a Jira issue is linked to a finding, the API response includes the Jira issue title alongside the existing issue ID and URL. You can filter the issue list by runtime validation verdict to narrow results to issues with specific validation outcomes. When an issue has been manually marked as non-exploitable, the response includes a nonExploitableReason field containing the human triage rationale (distinct from the system-generated validationSecurityAssessment). Patch status metadata now includes the current generation stage, so you can track patch progress in real time. You can retrieve all human triage rationales recorded against a repository’s findings — including false positives, non-exploitable verdicts, true positives, and severity changes — with a per-entry disposition field indicating the triage action. You can update free-form user notes on individual issues (org-shared, up to 5,000 characters; passing an empty or whitespace-only value clears the note). You can also regenerate patches for issues — and if an issue has been marked unpatchable, you can pass force=true to override that flag and request a fresh patch attempt
  • SCA — list dependency vulnerabilities with severity, reachability data, and patch status metadata when a remediation exists. You can filter SCA alerts and vulnerabilities to only those associated with applications exposed by Wiz
  • Reports — generate security reports in DOCX, CSV, SARIF, or SBOM format. If report generation fails, the report status is updated to failed with an error message describing what went wrong
  • Custom Reports — create, list, and delete saved filter configurations, retrieve aggregated statistics (severity distribution, top vulnerability classes, MTTR, trends), and discover available filter fields via the filter schema endpoint
  • Endpoints — semantic search across detected endpoints and data handlers
  • Agent — manage event triggers, patches, pull requests, global agent instructions, trigger history, real-time job streaming via SSE, and playbooks (activate, pause, and uninstall pre-built security automation workflows from a template library). Playbook templates support rich parameter types including text, number, boolean toggles, and select dropdowns, giving you fine-grained control when activating workflows. Read-only operations — including listing event triggers, playbook instances, trigger history, retrieving a specific trigger event, and reading global instructions — require only the Agent View permission; you do not need Agent Run to query these resources. Agent conversations and jobs are scoped by repository-level access control — if a conversation is bound to a repository, only users who hold view access on that repository can list, read, send messages to, or archive the conversation. Losing repository access automatically hides those conversations and jobs from all agent endpoints
  • On-Demand Code Scans Beta — submit diffs, files, and snippets for asynchronous security review from CLIs, IDEs, pre-commit hooks, and custom integrations
  • Rule Packs — browse curated bundles of natural-language SAST rule templates covering compliance, privacy, logging, and more; enable or disable individual templates or entire packs for your organization
  • Organizations — manage organizations, list/invite/remove members, and update member roles. When inviting a new member, you can optionally specify a role (ADMIN or MEMBER); the default is MEMBER, and inviting as ADMIN requires admin-level permission. The member list returns a clear status for each member — active, pendingInvite, or scimDeprovisioned — so you can distinguish active members from outstanding invitees and identity-provider-deprovisioned users. Removing a member works for active members and for pending or expired invitees (their outstanding invitation is automatically revoked); active admins cannot be removed directly — demote them to a regular member first. SCIM-deprovisioned members must be managed through your identity provider instead. Re-inviting an email address that already has a pending or expired invitation automatically revokes the old invitation and sends a fresh one
  • Repositories — list, add by URL (public repos), delete, and manage repository settings. For monorepo setups, you can atomically delete all partitions of a monorepo in a single operation, and previously deleted repositories can be re-imported without issues
  • Scans — trigger full scans, cancel running scans, and manage cron-based scan schedules with branch targeting. You can filter the scan list by severity level (Critical, High, Medium, Low) and group PR scans by pull request to see only the latest scan per PR along with a count of related rescans. If a full scan is already in progress for the same repository and branch, the API returns an error rather than starting a duplicate scan
  • Teams — create teams, manage memberships, configure granular organization/repository/team permissions, and manage default permission templates that can be applied to all teams or specific teams in your organization. Repository access can be granted globally (all repos), per-repository, or by tag — tag-based grants automatically cover every repository that belongs to the tag, so access stays in sync as repositories are added or removed. Updating or deleting a tag that has team permission grants requires the TEAM_MANAGE permission, and repository IDs supplied when creating or updating a tag are validated to belong to your organization. When reading a team’s permissions, the response includes a structured repoAccess field that explicitly indicates the access mode (universal or selected) along with the effective permissions, repository IDs, and tag IDs. The Agent Run permission implicitly includes Agent View — granting a team the ability to run the agent automatically grants view access as well, so you do not need to assign both permissions separately
  • Custom Sources — create, list, update, toggle, and delete custom security source declarations that tell the scanner about additional untrusted data entry points in your code
  • Custom Sinks — create, list, update, toggle, and delete custom security sink declarations that tell the scanner about additional security-sensitive operations in your code
  • Custom Source Packs — browse curated bundles of source declaration templates, enable or disable individual templates or entire packs
  • Custom Sink Packs — browse curated bundles of sink declaration templates, enable or disable individual templates or entire packs
  • Integrations — read data from third-party integrations such as Wiz CSPM, including retrieving Wiz settings, listing Wiz projects, and searching Wiz cloud assets and network exposures
  • Scanner Settings — configure scan modules, confidence thresholds, auto-patching, and file ignore patterns at org, repo, or app scope. The release track for full scans and PR scans accepts STABLE in addition to EDGE. The allowPrCheckBypass setting controls whether contributors can bypass the ZeroPath PR check status without disabling PR scanning entirely
  • Stats — retrieve aggregate issue counts and scan activity by scope, including a breakdown of issues by application with open and resolved counts per repository. Dashboard statistics endpoints accept optional application filters to narrow results to specific applications within repositories. The security posture summary includes a reachableExploitableIssues count alongside the existing severity-level counts
For a full list of available endpoints, see the API Reference.

​
Token Scopes

Tokens are organization-scoped. A token created under a specific organization grants access to all resources within that organization, subject to the same permissions as the user who created it. There is no fine-grained scope selection at token creation time — the token inherits the creating user’s permissions in the organization.

​
Managing Tokens

From the API Tokens settings page, you can:
  • View all active tokens with their names, creation dates, and expiration dates.
  • Delete tokens that are no longer needed or may be compromised.
Tokens cannot be edited after creation. To change a token’s expiration or name, delete it and create a new one.

​
Token Lifecycle

  • Tokens have a fixed expiration date set at creation (1–365 days).
  • Expired tokens are automatically rejected — there is no automatic renewal.
  • When a token expires, create a new one and update your integrations.
  • Token secrets are cryptographically hashed before storage — ZeroPath never stores the plaintext secret.

​
Best Practices

  1. Use descriptive names — name tokens after their purpose (e.g., “CI/CD Pipeline”, “VS Code Extension”, “MCP Server”).
  2. Set short expirations — use the shortest practical expiration for your use case.
  3. Rotate regularly — create new tokens and retire old ones on a schedule.
  4. Never commit tokens to source control — use environment variables or a secrets manager.
  5. One token per integration — avoid sharing a single token across multiple systems so you can revoke individually.
  6. Delete compromised tokens immediately — if a token may have been exposed, delete it and create a replacement.