Getting Started

Authentication & API Keys

Learn how Cloudizero secures requests via Bearer token authorization and how to configure key permissions safely.

API Key Structure

Cloudizero API Keys follow the standard format prefix:

cz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are hashed with bcrypt in the Cloudizero database, ensuring that even in the unlikely event of database access, plain keys cannot be compromised.

Using Keys in Environment Variables

Always store your API Key in environment variables instead of hardcoding it into source code:

.env.local

# .env.local
CLOUDIZERO_API_KEY="cz_live_9f8ab2e4..."
CLOUDIZERO_PROJECT_ID="ca2454ff-7f1e-421b-b134-4c800f6d58de"

Key Scoping & Least Privilege

When creating an API Key in the dashboard, you can choose between two scope modes:

All Projects: The key has read, upload, and delete permissions across all projects owned by your account. Ideal for central backend orchestration.
Project-Restricted: The key is locked exclusively to a single projectId. Any attempt to upload or list files outside this project is rejected with 403 Forbidden.

Client-Side vs Server-Side Architecture

Never expose secret keys on the browser

Do not initialize new Cloudizero({ apiKey: ... }) directly in public frontend React components with your secret key. Instead, generate a presigned URL on your backend, or use a Next.js Server Action / API proxy.

auth-request.ts

// Direct REST Request Header
fetch("https://cloudizero.wismannur.pro/api/storage/presign", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cz_live_9f8ab2e4...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ ... })
});