Chapter 3: Project Setup

Copied to clipboard!

Every Vibe CMS deployment starts with a project. Projects are the foundation of Vibe CMS's multi-tenant architecture, providing isolated environments where you can manage content, configure settings, and control team access. In this chapter, you'll learn how to create and configure your first project, manage API keys for programmatic access, and set up your team.

Understanding Projects

What Are Projects?

A project is the top-level container for all your CMS resources. Everything in Vibe CMS—collections, content items, files, locales, and configuration—exists within the scope of a project.

Project
├── Collections
│   ├── Content Items
│   └── Translations
├── Files & Folders
├── Locales
├── API Keys
└── Team Members

Key characteristics:

Isolation: Each project is completely isolated from others. Content, files, and settings in one project cannot be accessed from another.
Multi-tenancy: Multiple projects can exist under a single Vibe CMS instance, each serving different websites, applications, or clients.
Project-scoped access: Permissions, API keys, and team memberships are all scoped to individual projects.

Multi-Tenant Architecture

Vibe CMS is built on Basejump, a battle-tested multi-tenant framework for Supabase. This architecture ensures:

Row-Level Security (RLS): Every database query automatically enforces project boundaries at the PostgreSQL level
Account-based organization: Projects belong to accounts (personal or team)
Flexible permissions: Fine-grained role-based access control for team collaboration
Data separation: Complete isolation between projects with zero cross-contamination risk

Projects and Accounts

Projects are owned by accounts. There are two types of accounts:

Personal Accounts: Created automatically when you sign up. Ideal for individual users and small projects.
Team Accounts: Shared accounts that support multiple team members with different roles. Perfect for agencies, companies, and collaborative teams.

Each account can own multiple projects, and team members can be granted access with specific roles.

Creating Your First Project

Authentication Requirements

Important: Projects can only be created and managed using JWT authentication (user login). API keys are project-scoped and cannot be used to create or manage projects themselves.

Creating a Project Through the Admin UI

Log in to the Vibe CMS admin interface at your instance URL
Navigate to the Projects section in the account dashboard
Click "Create New Project"
Fill in the project details:
- Name: A human-readable name (e.g., "Marketing Website", "Blog Platform")
- Slug: URL-friendly identifier (auto-generated from name, can be customized)
- Description: Optional description of the project's purpose
Select the account that will own the project (personal or team account)
Click "Create Project"

Once created, the project is immediately available and you can start creating collections and content.

Project Metadata

Each project stores metadata including:

ID: Unique UUID identifier
Name: Display name
Slug: URL-friendly identifier
Account ID: The owning account
Created/Updated timestamps: Automatic tracking
Settings: Configuration object (JSON)

Best Practices for Project Naming

Descriptive names: Use clear, descriptive names that indicate the project's purpose
Consistent conventions: If managing multiple projects, use a consistent naming scheme
Environment indicators: Consider including environment in the name (e.g., "Blog - Production", "Blog - Staging")
Client projects: For agencies, prefix with client name (e.g., "Acme Corp - Website")

API Key Management

What Are API Keys?

API keys provide machine-to-machine authentication for programmatic access to your Vibe CMS project. They allow your applications to query content, upload files, and manage data without requiring user login.

Key characteristics:

Project-scoped: Each API key is tied to a specific project
Secure storage: Keys are hashed using bcrypt before storage
Instant revocation: Deleted keys are immediately invalidated
Expiration support: Optional expiration dates for enhanced security
Named keys: Assign descriptive names to track usage

Creating API Keys

Through the Admin UI

Open your project in the Vibe CMS admin interface
Navigate to Settings → API Keys
Click "Create API Key"
Configure the key:
- Name: Descriptive name (e.g., "Production Website", "Staging Deploy")
- Expiration: Optional expiration date (leave blank for no expiration)
Click "Generate Key"
Copy the key immediately: The full key is only shown once for security reasons

Through the API

You can also create API keys programmatically using JWT authentication:

curl -X POST https://your-instance.vibe-cms.com/api/v1/projects/{project_id}/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Website",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Website",
  "key": "vibe_pk_abc123def456...",
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2025-01-15T10:30:00Z"
}

Important: Store the key value securely. It will not be retrievable later.

API Keys vs JWT Tokens

Feature	API Keys	JWT Tokens
Use Case	Application/server access	User authentication
Scope	Single project	Account-wide
Lifespan	Long-lived (until revoked/expired)	Short-lived (hours)
Can Create Projects	❌ No	✅ Yes
Can Manage Content	✅ Yes	✅ Yes
Refresh Mechanism	Manual regeneration	Automatic refresh tokens

When to use API keys:

Server-side content fetching
Build-time static site generation
Automated workflows and scripts
CI/CD pipelines

When to use JWT tokens:

User login and authentication
Admin interface access
Project and account management
Team member operations

Security Best Practices

Key Storage

Never commit API keys to version control. Use environment variables:

# .env (add to .gitignore)
VIBE_CMS_API_KEY=vibe_pk_abc123def456...
VIBE_CMS_PROJECT_ID=550e8400-e29b-41d4-a716-446655440000

// Secure usage
const apiKey = process.env.VIBE_CMS_API_KEY;
const projectId = process.env.VIBE_CMS_PROJECT_ID;

Key Rotation

Rotate regularly: Change API keys periodically (quarterly or semi-annually)
Immediate revocation: If a key is compromised, delete it immediately—revocation is instant
Multiple keys: Use different keys for different environments (production, staging, development)

Expiration Policies

Set expiration dates for temporary access
Use short-lived keys for CI/CD and automated testing
Monitor expiring keys and rotate before expiration

Access Control

Principle of least privilege: Create separate keys for different use cases
Environment separation: Never use production keys in development/staging
Named keys: Use descriptive names to track purpose and usage

Revoking API Keys

To revoke an API key:

Navigate to Settings → API Keys in the admin UI
Find the key to revoke
Click "Delete" or "Revoke"
Confirm the action

The key is immediately invalidated and will fail all future authentication attempts.

Project Configuration

Default Locale

Every project must have a default locale. This is the fallback language used when:

No specific locale is requested
A translation is missing in the requested locale
Creating new content (auto-assigned to default locale)

To set the default locale:

Navigate to Settings → Locales
Find your preferred locale
Click "Set as Default"

Common default locales:

en-US (English - United States)
en-GB (English - United Kingdom)
de-DE (German - Germany)
fr-FR (French - France)

Locale Fallback Chains

Vibe CMS supports locale fallback to provide graceful degradation when translations are missing:

Requested: de-AT (German - Austria)
  ↓ (if not found)
Fallback: de-DE (German - Germany)
  ↓ (if not found)
Default: en-US (English - United States)

This ensures content is always available, even if specific regional translations haven't been created yet.

Project Settings

Project settings control various aspects of your CMS behavior:

Content versioning: Enable/disable automatic version snapshots
File upload limits: Maximum file sizes and allowed MIME types
Webhook endpoints: URLs for content change notifications
Cache TTL: Content cache duration for API responses
SEO defaults: Default meta tags and Open Graph settings

Access settings through Settings → Project Configuration in the admin UI.

Account and Team Management

Account Types

Personal Accounts

Created automatically on user registration
Owned by a single user
Ideal for individual developers and small projects
Can be upgraded to team accounts

Team Accounts

Support multiple team members with different roles
Shared billing and resource quotas
Collaborative content management
Role-based permissions

To create a team account:

Navigate to Account Settings
Click "Create Team Account"
Enter team name and details
Invite team members

Role-Based Permissions

Vibe CMS uses Basejump's role system with three levels:

Role	Permissions
Primary Owner	Full control, including account deletion and billing
Owner	Full project access, can invite members, cannot delete account
Member	Content editing and file management, cannot modify settings or invite users

Inviting Team Members

Open the team account dashboard
Navigate to Team → Members
Click "Invite Member"
Enter email address and select role
Click "Send Invitation"

The invitee receives an email with an invitation link. Once accepted, they gain access according to their assigned role.

Managing Team Access

Change roles: Owners can update member roles at any time
Remove members: Instantly revoke access by removing team membership
Transfer ownership: Primary owners can transfer ownership to another member
Audit logs: Track team member actions (if enabled)

Account Deletion and Data Handling

Warning: Deleting an account is permanent and irreversible.

When an account is deleted:

All projects owned by the account are deleted
All content, files, and configurations are permanently removed
Team members lose access immediately
API keys are revoked
Backups may be retained according to your retention policy

Only the primary owner can delete an account. This requires:

Confirmation via email verification
Re-entering the account password
Typing the account name to confirm

Security Considerations

Row-Level Security (RLS)

Vibe CMS enforces security at the database level using PostgreSQL Row-Level Security:

Automatic enforcement: All queries automatically filter by project and permissions
No application-level bypass: Security policies are enforced by PostgreSQL, not application code
Multi-layered protection: Even if application logic has bugs, RLS prevents unauthorized access

Example RLS policy:

CREATE POLICY "Users can only access their project's content"
  ON content_items
  FOR SELECT
  USING (
    project_id IN (
      SELECT project_id FROM account_memberships
      WHERE user_id = auth.uid()
    )
  );

Project Data Isolation

Projects are completely isolated:

No cross-project queries: API requests are scoped to a single project
Separate file storage: Files are stored in project-specific buckets
Independent configurations: Settings in one project don't affect others
Audit trail isolation: Activity logs are project-scoped

Authentication Flow Overview

┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       │ 1. Login (email/password)
       ▼
┌─────────────┐
│    Auth     │
│   Service   │
└──────┬──────┘
       │
       │ 2. Returns JWT token
       ▼
┌─────────────┐
│   Client    │───────────────────────┐
└──────┬──────┘                       │
       │                              │
       │ 3a. User operations          │ 3b. Create API key
       │    (JWT auth)                │    (JWT auth)
       ▼                              ▼
┌─────────────┐              ┌─────────────┐
│  Vibe CMS   │              │   Project   │
│     API     │              │  Settings   │
└─────────────┘              └──────┬──────┘
                                    │
                                    │ 4. Returns API key
                                    ▼
                             ┌─────────────┐
                             │ Application │
                             │   Server    │
                             └──────┬──────┘
                                    │
                                    │ 5. Content requests
                                    │    (API key auth)
                                    ▼
                             ┌─────────────┐
                             │  Vibe CMS   │
                             │     API     │
                             └─────────────┘

Zero-Trust Architecture Principles

Vibe CMS follows zero-trust security principles:

Verify explicitly: Every request is authenticated and authorized
Least privilege access: Users and API keys get minimum necessary permissions
Assume breach: Security layers prevent lateral movement even if one layer is compromised
Encryption in transit: All API communication uses HTTPS/TLS
Encryption at rest: Sensitive data is encrypted in the database

Security Best Practices Summary

✅ Do:

Use environment variables for API keys
Rotate API keys regularly
Set expiration dates for temporary access
Use different keys for different environments
Enable two-factor authentication (2FA) for user accounts
Monitor API usage and audit logs
Implement rate limiting in your applications

❌ Don't:

Commit API keys to version control
Share API keys between projects or environments
Use production keys in development
Disable RLS policies (not possible, but don't try to work around them)
Expose API keys in client-side code
Use the same password across accounts

Next Steps

Now that you've created and configured your first project, you're ready to:

Create collections to structure your content (Chapter 4)
Define fields to capture the data you need (Chapter 5)
Add content and translations (Chapter 6)
Integrate the SDK into your application (Chapter 7)

Your project is the foundation—everything you build in Vibe CMS starts here.

Next Chapter: Chapter 4: Collections and Content Types →