Information
- OpenAPI version:
3.1.0
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).
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.
Every token belongs to exactly one project and carries a subset of these scopes:
read — list/show repositories, scans, findings, presetsfindings:write — comment, change severity, change resolution, pin a noteguidance:write — read and update a repository’s guidance, and manage its audit areasscans:launch — start a scanregression-tests:write: generate regression tests and create their pull requestspublish — publish a finding or a scanadvisories:write — record which versions an advisory affectscontacts:read — read the advisory contact listcontacts:write — add an advisory contactautomations:write controls Continuous Security schedules, analyses, and budgetsreports:write — submit a vulnerability report to the programmeGET /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.
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 projectsrepositories:write connects repositories and moves them between projectsNo token can manage members, create tokens, archive or delete a project, or buy credits.
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>).
All errors share the envelope { "error": { "code": "...", "message": "..." } }.
Identity failures (bad/expired/revoked token) collapse to a generic 401.
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.
Project API token zkao_proj_<keyId>_<secret>, or organization token zkao_org_<keyId>_<secret>.
Security scheme type: http