Quickstart - CollabKit

This guide walks you through the complete setup: creating an account, setting up a room, adding users, and connecting the client SDK.

Prerequisites

Node.js 18+ installed
A running CollabKit server (self-hosted or managed)

1. Create an Account

2. Get Your API Key

Once logged in, go to Settings in the dashboard to find your Account ID and API Key.

Save both the accountId and apiKey. You’ll need them to construct the Bearer token for all API calls.

3. Create a Bearer Token

All API requests (except auth) use Bearer authentication. The token is a Base64-encoded string of accountId:apiKey:

ACCOUNT_ID="a1b2c3d4-5678-..."
API_KEY="7f3e8a2b9c1d4e5f..."
TOKEN=$(echo -n "${ACCOUNT_ID}:${API_KEY}" | base64)

4. Create a Room

curl -X POST https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/rooms \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-room"}'

Response

{
  "success": true,
  "data": {
    "room": {
      "id": "c3003c93-60cf-4184-...",
      "account_id": "a1b2c3d4-...",
      "name": "my-first-room",
      "state": "active",
      "created_at": "2026-05-29T..."
    }
  }
}

5. Create a User

Create a user in the room. This returns a JWT token that the client SDK uses for authentication:

ROOM_ID="c3003c93-60cf-4184-..."

curl -X POST https://api.collab-kit.com/v1/accounts/${ACCOUNT_ID}/users \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Alice\",
    \"roomId\": \"${ROOM_ID}\",
    \"profilePicture\": \"https://example.com/alice.png\"
  }"

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "f47ac10b-58cc-4372-...",
      "room_id": "c3003c93-...",
      "name": "Alice",
      "status": "offline"
    },
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

The token in the response is a JWT valid for 90 days. Pass it to the client SDK to authenticate WebSocket connections.

6. Install the Client SDK and Connect

npm install @collab-kit/client @collab-kit/utils

import CollabKitClient from '@collab-kit/client';

const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: 'eyJhbGciOiJIUzI1NiIs...', // JWT from step 5
});

// join() opens the WebSocket, authenticates with the JWT, and sets the user online.
// It defaults to { role: 'editor' }.
await client.join({ role: 'editor' });

// Or join as a viewer. Viewers receive updates and can follow users,
// but cannot write collaboration state.
// await client.join({ role: 'viewer' });

console.log('Connected as:', client.currentUser?.name);
console.log('Room:', client.currentRoom?.name);
console.log('Active editors:', client.users.active.size);

7. Add Real-Time Features

Now that you’re connected, add collaboration features:

// Share cursor position
document.addEventListener('mousemove', (e) => {
  client.presence.update({
    cursor: { x: e.clientX, y: e.clientY },
  });
});

// Listen to other users' cursors
client.presence.sync('*', ({ userId, state }) => {
  if (state) {
    renderCursor(userId, state.cursor);
  }
});

// Send a custom event
client.notifications.broadcast('emoji-reaction', {
  emoji: '🎉',
  x: 500,
  y: 300,
});

// Listen for events
client.notifications.on('emoji-reaction', (data) => {
  showFloatingEmoji(data.emoji, data.x, data.y);
});

import { defineStores } from '@collab-kit/utils';

const stores = defineStores({
  tasks: {
    title: { type: 'string', required: true },
    completed: { type: 'boolean', default: false },
  },
});

const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: '<jwt>',
  stores,
});

await client.join();

// Set a value (synced to all clients)
await client.stores.tasks.set({
  key: 'task-1',
  value: { title: 'Ship v1' },
});

Next Steps

Client SDK Reference

Full API reference for all SDK modules.

Guides & Examples

Build a cursor tracking experience and more.

API Reference

Detailed HTTP API documentation.

Webhooks & Workflows

Automate server-side actions on events.

​Prerequisites

​1. Create an Account

​2. Get Your API Key

​3. Create a Bearer Token

​4. Create a Room

​5. Create a User

​6. Install the Client SDK and Connect

​7. Add Real-Time Features

​Next Steps

Client SDK Reference

Guides & Examples

API Reference

Webhooks & Workflows

Prerequisites

1. Create an Account

2. Get Your API Key

3. Create a Bearer Token

4. Create a Room

5. Create a User

6. Install the Client SDK and Connect

7. Add Real-Time Features

Next Steps