API Tokens

​

Overview

​

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.

• Token ID — a UUID identifying the token (safe to log).
• Token Secret — the secret key (treat like a password).

​

Authentication Headers

X-ZeroPath-API-Token-Id: <your-token-id>
X-ZeroPath-API-Token-Secret: <your-token-secret>

​

Optional: Client identification header

X-ZeroPath-Client: cli

​

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

• Vulnerabilities — list, search, and manage security findings, including remediation and patch metadata when available. Issue details include a tickets array listing every linked issue tracker ticket — each entry contains the provider (jira or linear), the ticket key, and the ticket url (or null when a URL is not available). The bulk issue export also includes this tickets array on each exported finding, so you can reconcile an export against the Jira or Linear tickets that ZeroPath filed for those findings. When a Jira issue is linked to a finding, the API response also 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). The issue detail response also includes an exploitationSetup field — a plain-language description of the configuration or modification a running application would need before the finding can be exploited (empty string when the validator did not characterize it). 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. When regenerating, you can supply optional feedback (up to 4,000 characters of free-form guidance forwarded to the patch agent) and a variantCount (1–3) to generate multiple alternative patch candidates instead of applying one directly; the issue detail response includes a patchCandidates array listing each pending alternative (with its diff, PR title, PR description, and blast-radius report) so you can review them before choosing; use issues.selectPatchCandidate to promote your preferred candidate into the issue patch and discard the rest. You can update the severity rating of an issue by label (e.g., downgrade a “High” to “Medium”) — the platform adjusts the underlying severity score to land in the requested band. Cross-repository evidence is included in issue details when the scanner identifies related code across multiple repositories, giving you full visibility into multi-repo vulnerability chains. You can exclude specific repository branches from issue list results using excludedRepositoryBranches filters. The issue list input now uses strict validation — unknown or unrecognized properties in the request body are rejected with an error rather than silently ignored, so you should remove any unsupported filter fields from your requests. Issue details now include Wiz runtime evidence when a Wiz integration is connected, providing workload context such as running status, sensitive data exposure, internet reachability, and attribution details for the repository’s deployed workloads — both at the time of detection and the latest lookup. The issue detail response now includes a securityCompassCountermeasures array listing every SD Elements countermeasure linked to the issue — each entry includes the mapping id, project id, task id, title, a link back to the SD Elements task, the match method (NL_RULE_FK for deterministic rule-based links or LLM for model-matched links), whether it is the primary countermeasure reported against in SD Elements, and the model rationale for LLM matches
• SCA — list dependency vulnerabilities with severity, reachability data, and patch status metadata when a remediation exists. The vulnerability search endpoint uses cursor-based pagination with hasMore and nextCursor fields; to retrieve the total count of matching findings, use the dedicated count endpoint (/api/v1/sca/vulnerabilities/count) which accepts the same filter parameters — including scanId to count findings from a specific scan, status to filter by lifecycle state (all, open, or closed), severities and packageReachability to narrow by severity bucket or reachability verdict, isCompiled to distinguish compiled assets from manifest-declared dependencies, hasFix to count only findings with a recommended fix version, and includeEphemeral to include ephemeral repositories. You can filter SCA alerts and vulnerabilities to only those associated with applications exposed by Wiz. SCA advisories now include exploit intelligence fields — CISA KEV status (isKnownExploited, kevDateAdded, kevKnownRansomware) and FIRST EPSS scores (epssScore, epssPercentile) — so you can prioritize based on real-world exploitation data. You can list dependency-resolution coverage warnings to identify manifests where the dependency tree could not be fully resolved, and query per-ecosystem resolution coverage to quantify how complete your dependency scanning is across repositories. When listing SCA facet options, you can pass a facets parameter to selectively compute only the option lists you need (dependencies, advisories, or ecosystems) — asking for fewer facets is faster, and omitting the parameter computes all of them
• 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. Recurring (cron-triggered) agent jobs are automatically linked to a Schedules tab entry — if a run arrives without an existing schedule record, one is created so every recurring task is visible and can be paused from the dashboard; a run for a schedule you have already paused is silently skipped rather than executed
• 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. Rule pack activation requires a user account — agent sessions receive a permission error
• Custom Rules — create, update, and list natural-language security rules. Rules can be scoped to all repositories (default), specific repositories, or by tag — pass tagIds without repositoryIds to scope a rule to repositories carrying those tags. Each rule’s response includes a scope field (allRepositories, repositories, or tags) so you can see how it is applied. List and get responses also include a source field (USER or SECURITY_COMPASS) indicating whether the rule was created manually or auto-generated from an SD Elements countermeasure
• 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. GitHub team sync status includes a lastTeamSyncAt timestamp showing when the most recent sync completed, and you can trigger an immediate on-demand sync via the API or the dashboard. You can enable or disable GitHub direct collaborator sync for your organization, which syncs individual repository collaborator permissions alongside team-based access. When a sync encounters an error, the sync status response includes a syncError field with the error message, so you can diagnose issues without contacting support. Direct collaborator sync is not supported for GitHub Enterprise Server installations
• Repositories — list, add by URL (public repos), delete, and manage repository settings. Repository responses include VCS-specific configuration for GitHub, GitLab, Bitbucket, Azure DevOps, Gerrit, generic Git, and CVS repositories, so you can identify the source provider and connection status for each repository. 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. Tags can be marked as default (isDefault: true) so they are automatically applied to every newly added repository, ensuring consistent tagging and team access from the moment a repository is imported. Repository objects now include a lastScanError field (string or null) with the error message from the most recent failed scan, giving you visibility into why a scan did not complete without having to inspect individual scan records. The defaultBranch field is now string | null — it returns null for repositories that the VCS reports as having no default branch (for example, a newly created empty repository). When resetting repository scanner settings, the response returns a resetCount field indicating the number of repository scopes whose overrides were cleared
• Container Scanning — submit container images for vulnerability scanning by registry reference or by uploading an image archive (for air-gapped environments). You can list and retrieve tracked container images, view scan results with per-layer attribution and base-image upgrade recommendations, list vulnerability findings grouped by package with aggregated CVEs, and manage recurring monitoring schedules via cron expressions. The container dashboard summary provides organization-wide statistics including image counts, findings by severity, and top base-image upgrade opportunities. You can link images to repositories, delete tracked images, and check whether container scanning is enabled for your organization. Container image objects include a registryConnection field (containing id and displayName, or null) that identifies an org-level registry connection supplying pull credentials — a reusable alternative to inline per-image credentials. When submitting an image, you can pass registryConnectionId to link an existing org-level connection instead of providing inline registryUsername/registryToken; these two approaches are mutually exclusive. Passing clearRegistryAuth clears both inline credentials and any linked registry connection, reverting the image to an anonymous pull. The monitoringCrontab field on the submit request accepts three states: a string sets the schedule, an explicit null clears an existing schedule, and omitting the field leaves any existing schedule unchanged. Submitting a registry image reference that matches the name of an existing uploaded-archive image in the same repository returns a 409 Conflict — use a different name or attach the image to a different repository to resolve the conflict
• Scans — trigger full scans, cancel running scans, and manage cron-based scan schedules with branch targeting. Scan responses include repository identifiers for all supported VCS providers (GitHub, GitLab, Bitbucket, Azure DevOps, Gerrit, Generic Git, and CVS). You can scan all VCS-attached repositories at once by passing allRepositories: true, optionally excluding specific repositories with excludedRepositoryIds. 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. Scan list results respect per-repository access control — you only see scans for repositories you have view access to, consistent with how access control works across all other platform surfaces. 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. When rescanning a PR, the force flag now runs a full scan instead of an incremental refresh. When starting a multi-repository scan, repositories that cannot be scanned (for example, due to missing branch configuration or billing issues) are automatically skipped rather than blocking the entire batch — the remaining eligible repositories proceed normally. For credit-billed scans, if the repository’s usage estimate is still being computed at quote time, the scan proceeds immediately and is billed at the pricing policy’s minimum charge — the estimatedBillableTokens field in the quote response will be null in this case rather than a token count
• Runtime Validation — dynamically test confirmed findings inside isolated containers. You can auto-provision a source-build validation profile for a single application (runtimeValidation.autoProvisionAndValidate) or for every detected application in a repository at once (runtimeValidation.autoProvisionAndValidateRepository) — no manual profile configuration or uploaded artifact required, just supply a completed scan id. Applications already queued are skipped automatically. Runtime validation profiles now support a SOURCE_BUILD target mode in addition to REMOTE_CONNECTIVITY and LOCAL_ARTIFACT; source-build profiles are built and run directly from the repository source inside the validation environment. Each finding carries a setupRequirement field (DEFAULT_SETUP, REQUIRES_MODIFICATION, or UNKNOWN) indicating whether it is reachable under the default provisioned environment. After a run completes you can call runtimeValidation.listExploitChains to retrieve multi-step exploit chains — sequences of confirmed findings that, when chained together, reach higher combined impact than any individual finding — ordered by combined severity and including per-step roles, configuration requirements, proof-of-concept instructions, and a setup requirement for the chain as a whole
• 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. When GitHub direct collaborator sync is enabled for your organization, each user’s effective repository access is the union of their team-based grants and their individual GitHub collaborator permissions — so a user who is a direct collaborator on a GitHub repository can access it in ZeroPath even if none of their teams grant access to that repository. Contributors discovered through direct collaborator sync are surfaced in the unmatched contributors list with a DIRECT_REPOSITORY provenance indicator, distinct from team-sourced contributors, so you can see how each contributor’s access was derived. 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. You can customize how GitHub repository roles (Pull, Triage, Push, Maintain, Admin) map to ZeroPath repository permissions during GitHub team sync. Use teams.getGithubSyncRolePermissions to view the current mapping and ZeroPath’s built-in defaults, and teams.setGithubSyncRolePermissions to replace it with a custom mapping or reset to defaults. Custom mappings must specify all five GitHub roles at once so the stored mapping is always complete. Changes take effect on the next sync — existing synced permissions are reconciled at that time. Viewing the mapping requires the Team View permission; updating it requires Team Manage
• 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
• Security Compass — manage the SD Elements integration end-to-end via the public REST API (/api/v2/securityCompass/*): read the integration and project mappings, test the connection, add and remove project-to-repository mappings, trigger countermeasure-to-rule syncs, retrieve the per-countermeasure coverage audit, fetch linked findings for a countermeasure, and view the Security Compass audit log. Credentials (the SD Elements API token and base URL) are managed only in the ZeroPath dashboard — the API never accepts or returns them. Testing the connection requires the same admin-level permission as managing the integration — the test connection endpoint validates both authentication and the target URL before dialing. Managing the integration requires the admin role; read operations are available to all members. See the Security Compass integration guide for the full workflow
• Scanner Settings — configure scan modules, confidence thresholds, auto-patching, and file ignore patterns at org, repo, or app scope. When deleting scanner settings overrides for a scope, organization and repository scopes retain their assigned rules, contexts, custom sources/sinks, and pattern sets while reverting configuration overrides; tag scopes are removed entirely, unassigning any records attached to them. Enabled scan modules now include CONTAINER alongside SAST, IAC, SECRETS, EOL, SCA, and AI. 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. The fullScanAutoProvisionRuntimeValidation setting enables automatic source-build runtime validation provisioning after each full scan, so detected applications are validated without any manual profile configuration. The scanOnFirstMeaningfulCommit setting (boolean or null to inherit) controls whether ZeroPath automatically triggers a scan when a repository receives its first meaningful commit, useful for repositories that are initially empty at import time
• 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. If the requested posture scope is too large to compute within the query time budget, the endpoint returns a 408 response — retry with fewer repositories, as repeating the same scope will not succeed

​

Token Scopes

​

Managing Tokens

• View all active tokens with their names, creation dates, and expiration dates.
• Delete tokens that are no longer needed or may be compromised.

​

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.