Information
- OpenAPI version:
3.1.0
Overview
zkao Project API 1.0.0
Section titled “zkao Project API 1.0.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).
Authentication
Send the token in the Authorization header: Authorization: Bearer zkao_proj_<keyId>_<secret>.
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, 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 scanpublish— publish a finding or a scan
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.
Organizations
Every project belongs to an organization, which holds the prepaid credit
balance shared by all of its projects. Tokens stay project-scoped: the
billing endpoints report the organization’s balance as seen from this
project, and usage attributed to this 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.
Authentication
Section titled “ Authentication ”bearerAuth
Section titled “bearerAuth”Project API token: zkao_proj_<keyId>_<secret>.
Security scheme type: http