API Reference

The Control Zero API provides programmatic access to manage projects, policies, and audit logs.

Authentication

All API requests require authentication using an organization-level API token or a project-level API key.

Organization Token

Organization tokens have access to all projects within the organization. Use these for management operations like creating projects and managing policies.

curl -H "Authorization: Bearer YOUR_ORG_TOKEN" \
  https://api.controlzero.dev/v1/projects

Project API Key

Project API keys are scoped to a single project. SDKs use these to download policy bundles and submit audit logs.

curl -H "Authorization: Bearer cz_live_your_api_key_here" \
  https://api.controlzero.dev/v1/projects/proj_abc123/bundle

Base URL

All API endpoints are served from:

https://api.controlzero.dev/v1

Request Format

• All request bodies must be JSON with Content-Type: application/json.
• All responses are JSON.
• Timestamps are in ISO 8601 format (UTC).

Response Format

Successful responses return the requested data:

{
  "id": "proj_abc123",
  "name": "production-agents",
  "created_at": "2026-03-01T00:00:00Z"
}

Error responses include an error code and message:

{
  "error": {
    "code": "not_found",
    "message": "Project not found"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Resource created
400	Bad request -- invalid parameters
401	Unauthorized -- missing or invalid authentication
403	Forbidden -- insufficient permissions
404	Not found
429	Rate limited
500	Internal server error

Required Headers

Header	Required	Description
X-ControlZero-Agent-ID	Required	Identifies the agent making the call. Requests without this header are rejected with 400.
X-API-Key	Required	Control Zero API key (czlive_ or cztest_)
X-ControlZero-Identity-Token	Recommended	JWT token for user-level principal resolution
X-ControlZero-User-ID	Optional	User ID for identity context in policy evaluation
X-ControlZero-User-Group	Optional	User group for RBAC policy evaluation

Rate Limiting

API requests are rate limited per organization:

• Management endpoints: 100 requests per minute
• Policy bundle downloads: 600 requests per minute
• Audit log submission: 1000 requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709251260

Endpoints

Projects

Method	Path	Description
GET	/v1/projects	List all projects
POST	/v1/projects	Create a new project
GET	/v1/projects/:id	Get a project by ID
PATCH	/v1/projects/:id	Update a project
DELETE	/v1/projects/:id	Delete a project

Policies

Method	Path	Description
GET	/v1/projects/:id/policies	List policies for a project
POST	/v1/projects/:id/policies	Create a new policy
GET	/v1/projects/:id/policies/:policy_id	Get a policy by ID
PUT	/v1/projects/:id/policies/:policy_id	Update a policy
DELETE	/v1/projects/:id/policies/:policy_id	Delete a policy
POST	/v1/projects/:id/policies/:policy_id/publish	Publish a policy

Policy Bundles

Method	Path	Description
GET	/v1/projects/:id/bundle	Download the latest policy bundle
GET	/v1/projects/:id/bundle/version	Get the current bundle version

API Keys

Method	Path	Description
GET	/v1/projects/:id/keys	List API keys for a project
POST	/v1/projects/:id/keys	Create a new API key
DELETE	/v1/projects/:id/keys/:key_id	Revoke an API key

Secrets (Optional)

Secrets endpoints allow programmatic management of encrypted provider keys. See Secrets Management for details.

Method	Path	Description
GET	/v1/projects/:id/secrets	List secrets for a project (metadata only)
POST	/v1/projects/:id/secrets	Store a new encrypted secret
GET	/v1/projects/:id/secrets/:secret_id	Get secret metadata
DELETE	/v1/projects/:id/secrets/:secret_id	Permanently delete a secret

note

Secret values are encrypted before storage. The POST response includes the plaintext value exactly once. Subsequent GET requests return only metadata and a masked prefix.

Audit Logs

Method	Path	Description
GET	/v1/projects/:id/audit-logs	List audit log entries
POST	/v1/projects/:id/audit-logs	Submit audit log entries (used by SDKs)

Health

Method	Path	Description
GET	/v1/health	API health check

Pagination

List endpoints support cursor-based pagination:

curl "https://api.controlzero.dev/v1/projects/proj_abc123/audit-logs?limit=50&cursor=eyJpZCI6MTAwfQ"

Parameter	Type	Default	Description
limit	int	50	Number of results per page (max 100).
cursor	string	--	Cursor from a previous response for the next page.

Paginated responses include a next_cursor field:

{
  "data": [...],
  "next_cursor": "eyJpZCI6MTUwfQ",
  "has_more": true
}

SDKs

For most use cases, we recommend using the official SDKs instead of calling the API directly:

• Python SDK
• Go SDK
• Node.js SDK

The SDKs handle authentication, policy bundle caching, and audit log submission automatically.

Note: Bundle signature verification is enforced as of SDK version 0.3.0. Ensure you are using an SDK version that includes this feature.