Documentation · Yorkie

If you want to update this page or add new content, please submit a pull request to the Homepage.

On this page

Projects

A Project in Yorkie is a logical grouping that isolates documents, channels, and clients. Projects enable multi-tenancy, allowing you to run multiple independent applications or environments within a single Yorkie installation.

Overview

Every Yorkie installation starts with a default project that is created automatically. When a Client connects without specifying an API key, it is placed in the default project. For production applications, you should create dedicated projects to isolate data and configure settings independently.

Project Isolation

Each project provides complete isolation:

Documents in one project are invisible to clients in another project. A document key like doc-1 can exist independently in multiple projects.
Channels are scoped to their project. Broadcast messages and presence updates only reach clients within the same project.
Clients belong to exactly one project, determined by the API key they use to connect.
Configuration (auth webhooks, event webhooks, resource limits, housekeeping thresholds) is set per project.

API Keys

Each project has two keys:

Key	Purpose	Usage
Public Key	Identifies the project for client connections	Used as `apiKey` when creating a Client
Secret Key	Authenticates server-side applications	Used in the `authorization` header for Admin API requests

1// Connect a client to a specific project using its public key
2const client = new yorkie.Client({
3  rpcAddr: 'https://api.yorkie.dev',
4  apiKey: 'your-project-public-key',
5});

Keep your Secret Key confidential. It grants full access to manage documents within the project via the Admin API. Never expose it in client-side code.

Managing Projects

Projects are managed through the CLI or the Dashboard.

Creating a Project

$ yorkie project create my-app-prod

This returns the project details including both keys:

{
  "name": "my-app-prod",
  "public_key": "...",
  "secret_key": "...",
  "created_at": "..."
}

Listing Projects

$ yorkie project ls

Updating a Project

Configure project settings such as auth webhooks, event webhooks, and resource limits:

# Set an auth webhook URL
$ yorkie project update my-app-prod --auth-webhook-url https://my-server.com/auth

# Configure event webhooks
$ yorkie project update my-app-prod \
  --event-webhook-url https://my-server.com/events \
  --event-webhook-events-add DocumentRootChanged

# Set resource limits
$ yorkie project update my-app-prod \
  --max-attachments-per-document 50 \
  --max-subscribers-per-document 100

# Configure housekeeping
$ yorkie project update my-app-prod \
  --client-deactivate-threshold 24h

For the full set of update options, see Updating the Project.

Per-Project Configuration

Each project can be independently configured with the following settings:

Setting	Description	Reference
Auth Webhook	External authentication endpoint for validating client requests	Security: Auth Webhook
Event Webhook	Notification endpoint for document events	Event Webhook
Allowed Origins	CORS restrictions for client connections	Security: Allowed Origins
Max Attachments	Maximum clients that can attach to a single document	Document Limits
Max Subscribers	Maximum clients that can subscribe to a single document	Document Limits
Client Deactivate Threshold	Time after which inactive clients are automatically deactivated by Housekeeping	CLI

Common Patterns

Separate Environments

Create distinct projects for development, staging, and production:

$ yorkie project create my-app-dev
$ yorkie project create my-app-staging
$ yorkie project create my-app-prod

Use environment variables in your application to select the appropriate API key:

1const client = new yorkie.Client({
2  rpcAddr: process.env.YORKIE_RPC_ADDR,
3  apiKey: process.env.YORKIE_API_KEY,
4});

Multiple Applications

If you host multiple collaborative applications on a single Yorkie server, create a project for each:

$ yorkie project create docs-app
$ yorkie project create whiteboard-app
$ yorkie project create chat-app

Each application's documents, channels, and client data remain fully isolated.