Proyek

Proyek adalah unit organisasi tingkat atas di Control Zero. Sebuah proyek mengelompokkan kebijakan, kunci API, dan log audit untuk sekumpulan agen AI tertentu.

Apa Itu Proyek?

Sebuah proyek mewakili batas logis untuk tata kelola. Biasanya, Anda membuat satu proyek per lingkungan (mis., production, staging) atau per aplikasi (mis., customer-support-agent, data-pipeline-agent).

Setiap proyek memiliki:

• Project ID yang unik (mis., proj_abc123).
• Satu atau beberapa kunci API untuk autentikasi SDK.
• Sekumpulan kebijakan yang menentukan aturan tata kelola untuk agen dalam proyek ini.
• Log audit dari semua keputusan kebijakan yang dibuat oleh SDK yang terhubung ke proyek ini.

Membuat Proyek

Anda dapat membuat proyek melalui dasbor Control Zero atau melalui API.

Dasbor

1. Buka Projects di bilah samping.
2. Klik Create Project.
3. Masukkan nama dan deskripsi opsional.
4. Klik Create.

API

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

Respons:

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

Kunci API

Setiap proyek memiliki kunci API yang digunakan SDK untuk mengautentikasi dan mengunduh bundel kebijakan.

Jenis Kunci

Jenis	Prefiks	Tujuan
Live	cz_live_	Penggunaan produksi. Penerapan kebijakan penuh dan pencatatan audit.
Test	cz_test_	Pengembangan dan pengujian. Kebijakan dievaluasi tetapi aksi tidak pernah diblokir (mode hanya-log).

Mengelola Kunci

Anda dapat membuat, merotasi, dan mencabut kunci API dari halaman pengaturan proyek.

• Buat: Hasilkan kunci baru untuk proyek. Anda dapat memiliki beberapa kunci aktif secara bersamaan.
• Rotasi: Hasilkan kunci baru dan tetapkan masa berlaku pada kunci lama. Ini memungkinkan rotasi kunci tanpa downtime.
• Cabut: Langsung membatalkan sebuah kunci. SDK mana pun yang menggunakan kunci yang dicabut akan kehilangan akses pada penyegaran kebijakan berikutnya.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

waspada

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

Menggunakan Kunci di SDK

Berikan kunci API saat menginisialisasi SDK:

# Python
from controlzero import Client

client = Client(api_key="cz_live_your_api_key_here")

// Go
client, err := controlzero.New(
    controlzero.WithAPIKey("cz_live_your_api_key_here"),
)

Anda juga dapat menyetel kunci API melalui variabel lingkungan:

export CONTROLZERO_API_KEY="cz_live_your_api_key_here"

Kunci API menentukan proyek.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Each key belongs to exactly one project, and the project identity arrives inside the signed policy bundle — there is no CONTROLZERO_PROJECT_ID environment variable.

Jalankan controlzero whoami untuk melihat proyek dan organisasi mana yang dipetakan oleh kunci di lingkungan Anda.

Penugasan Kebijakan

Kebijakan ditugaskan pada tingkat proyek. Ketika Anda membuat atau mengubah kebijakan dalam sebuah proyek, kebijakan tersebut otomatis disertakan dalam bundel kebijakan berikutnya yang dikompilasi untuk proyek itu.

Kebijakan Aktif

Hanya kebijakan yang dipublikasikan yang disertakan dalam bundel kebijakan. Kebijakan draf tidak diterapkan.

Sebuah proyek dapat memiliki beberapa kebijakan aktif. Semua kebijakan aktif dievaluasi untuk setiap pemeriksaan aksi. Aturan dari semua kebijakan digabungkan dan dievaluasi bersama menggunakan urutan evaluasi standar.

Pembuatan Versi Kebijakan

Setiap kali Anda mempublikasikan kebijakan, sebuah versi baru dibuat. Anda dapat:

• Melihat riwayat semua versi kebijakan.
• Kembali ke versi sebelumnya jika diperlukan.
• Membandingkan versi untuk melihat apa yang berubah.

Pengaturan Proyek

Pengaturan	Deskripsi	Default
Default Effect	Efek yang diterapkan ketika tidak ada aturan kebijakan yang cocok dengan aksi.	deny
Bundle Refresh Interval	Seberapa sering SDK melakukan polling bundel kebijakan baru (dalam detik). Default SDK berbeda: Python 60, Node 300.	60
Log-Only Mode	Jika diaktifkan, kebijakan dievaluasi dan dicatat tetapi aksi tidak pernah diblokir.	false

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

Audit log retention is not a project setting. It is configured per organization, defaults to 30 days today, and an owner can set it between 1 and 2555 days; see Account Management.

Mengorganisasi Proyek

Berikut pola umum untuk mengorganisasi proyek:

Berdasarkan lingkungan: Buat proyek terpisah untuk production, staging, dan development. Ini memungkinkan Anda menerapkan kebijakan ketat di produksi sambil menjaga development tetap lebih permisif.

Berdasarkan aplikasi: Buat proyek untuk setiap aplikasi agen yang berbeda.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

This isolates policies and audit logs per application.

Berdasarkan tim: Buat proyek per tim untuk mendelegasikan pengelolaan kebijakan sambil mempertahankan pengawasan organisasi.

Teks asli berbahasa Inggris -- terjemahan menunggu tinjauan teknis

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