Skip to content
These docs describe staging.zkao.io and the @zksecurity/zkao-cli@next release. For production, see docs.zkao.io.

Overview

View .md

Project-scoped REST API for programmatically controlling a single zkao project with a bearer API token (created under Project Settings → Integrations, or approved through the CLI’s zkao login).

Authentication

Send the token in the Authorization header: Authorization: Bearer zkao_proj_<keyId>_<secret>. An organization token reads zkao_org_<keyId>_<secret> and is sent the same way. The token is shown once at creation and never again. Passing the token in the query string is rejected.

Scoping (what a token can do)

Every token belongs to exactly one project and carries a subset of these scopes:

  • read — list/show repositories, scans, findings, presets
  • findings:write — comment, change severity, change resolution, pin a note
  • guidance:write — read and update a repository’s guidance, and manage its audit areas
  • scans:launch — start a scan
  • regression-tests:write: generate regression tests and create their pull requests
  • publish — publish a finding or a scan
  • advisories:write — record which versions an advisory affects
  • contacts:read — read the advisory contact list
  • contacts:write — add an advisory contact
  • automations:write controls Continuous Security schedules, analyses, and budgets
  • reports:write — submit a vulnerability report to the programme

GET /token tells a token which project, and which organization, it belongs to.

A token may also be restricted to a subset of the project’s repositories (a repo allowlist). Any resource outside the token’s project or repo allowlist responds 404 (never confirmed to exist). Launching a scan requires the project’s organization to have prepaid credits.

Organization tokens

An organization token reaches every project of one organization, including projects created later. An owner or admin of the organization approves one with zkao login --org, and revokes it in the organization’s settings. It works on every /projects/{projectId}/... route of its organization with the scopes above, and it has no repo allowlist. A project of another organization responds 404. Its spend limit and its request limit each count across the whole organization. The spend limit is measured per calendar month in UTC.

Only an organization token may carry these scopes, which the /organizations/{organizationId}/... routes require:

  • projects:write creates and renames projects
  • repositories:write connects repositories and moves them between projects

No token can manage members, create tokens, archive or delete a project, or buy credits.

Organizations

Every project belongs to an organization, which holds the prepaid credit balance shared by all of its projects. The billing endpoints report the organization’s balance as seen from one project, and usage attributed to that project. Projects and repositories also carry a slug, the readable segment used in app URLs (/orgs/<org>/projects/<project>/repos/<repo>).

Errors

All errors share the envelope { "error": { "code": "...", "message": "..." } }. Identity failures (bad/expired/revoked token) collapse to a generic 401.

Polling and rate limits

When polling a scan, honor the advisory Retry-After header on the scan response rather than polling in a tight loop. A token that sends too many requests receives 429 with a Retry-After header; back off until then. The official SDK’s waitForScan does this for you.

Information

  • OpenAPI version: 3.1.0

Project API token zkao_proj_<keyId>_<secret>, or organization token zkao_org_<keyId>_<secret>.

Security scheme type: http