Projects

Projects are the top-level organizational unit in Control Zero. A project groups together policies, API keys, and audit logs for a specific set of AI agents.

What Are Projects?

A project represents a logical boundary for governance. Typically, you create one project per environment (e.g., production, staging) or per application (e.g., customer-support-agent, data-pipeline-agent).

Each project has:

• A unique Project ID (e.g., proj_abc123).
• One or more API keys for SDK authentication.
• A set of policies that define the governance rules for agents in this project.
• An audit log of all policy decisions made by SDKs connected to this project.

Creating a Project

You can create projects through the Control Zero dashboard or via the API.

Dashboard

1. Navigate to Projects in the sidebar.
2. Click Create Project.
3. Enter a name and optional description.
4. Click Create.

API

curl -X POST https://api.controlzero.dev/v1/projects \
  -H "Authorization: Bearer YOUR_ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-agents",
    "description": "Production AI agent governance"
  }'

Response:

{
  "id": "proj_abc123",
  "name": "production-agents",
  "description": "Production AI agent governance",
  "created_at": "2026-03-01T00:00:00Z"
}

API Keys

Each project has API keys that SDKs use to authenticate and download policy bundles.

Key Types

Type	Prefix	Purpose
Live	cz_live_	Production use. Full policy enforcement and audit logging.
Test	cz_test_	Development and testing. Policies are evaluated but actions are never blocked (log-only mode).

Managing Keys

You can create, rotate, and revoke API keys from the project settings page.

• Create -- Generate a new key for the project. You can have multiple active keys simultaneously.
• Rotate -- Generate a new key and set an expiration on the old key. This allows for zero-downtime key rotation.
• Revoke -- Immediately invalidate a key. Any SDK using the revoked key will lose access on its next policy refresh.

caution

API keys are shown only once at creation time. Store them securely. If you lose a key, you must create a new one.

Using Keys in SDKs

Pass the API key when initializing the SDK:

# Python
client = controlzero.ControlZero(
    api_key="cz_live_your_api_key_here",
    project_id="proj_abc123",
)

// Go
client, err := controlzero.NewClient(
    controlzero.WithAPIKey("cz_live_your_api_key_here"),
    controlzero.WithProjectID("proj_abc123"),
)

You can also set the API key via environment variables:

export CONTROLZERO_API_KEY="cz_live_your_api_key_here"
export CONTROLZERO_PROJECT_ID="proj_abc123"

Policy Assignment

Policies are assigned at the project level. When you create or modify a policy within a project, it is automatically included in the next policy bundle compiled for that project.

Active Policies

Only published policies are included in policy bundles. Draft policies are not enforced.

A project can have multiple active policies. All active policies are evaluated for every action check -- the rules from all policies are combined and evaluated together using the standard evaluation order.

Policy Versioning

Each time you publish a policy, a new version is created. You can:

• View the history of all policy versions.
• Roll back to a previous version if needed.
• Compare versions to see what changed.

Project Settings

Setting	Description	Default
Default Effect	The effect applied when no policy rule matches an action.	deny
Bundle Refresh Interval	How often SDKs poll for new policy bundles (in seconds).	60
Audit Log Retention	How long audit log entries are retained.	90 days
Log-Only Mode	When enabled, policies are evaluated and logged but actions are never blocked.	false

Organizing Projects

Here are common patterns for organizing projects:

By environment -- Create separate projects for production, staging, and development. This lets you apply strict policies in production while keeping development more permissive.

By application -- Create a project for each distinct agent application. This isolates policies and audit logs per application.

By team -- Create projects per team to delegate policy management while maintaining organizational oversight.

You can combine these patterns. For example, customer-support-production and customer-support-staging give you both application and environment isolation.