> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Tokens

> Create and manage API tokens for programmatic access to ZeroPath

## 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](https://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:

```bash theme={null}
X-ZeroPath-API-Token-Id: <your-token-id>
X-ZeroPath-API-Token-Secret: <your-token-secret>
```

### Example

```bash theme={null}
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
* **SCA** — list dependency vulnerabilities with severity, reachability data, and patch status metadata when a remediation exists
* **Reports** — generate security reports in DOCX, CSV, SARIF, or SBOM format
* **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)
* **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
* **Repositories** — list, add by URL (public repos), delete, and manage repository settings
* **Scans** — trigger full scans, cancel running scans, and manage cron-based scan schedules with branch targeting
* **Teams** — create teams, manage memberships, and configure granular organization/repository/team permissions
* **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
* **Scanner Settings** — configure scan modules, confidence thresholds, auto-patching, and file ignore patterns at org, repo, or app scope
* **Stats** — retrieve aggregate issue counts and scan activity by scope

For a full list of available endpoints, see the [API Reference](/api-reference/introduction).

## 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.