> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get real-time collaboration running in your apps and agents in under 5 minutes.

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

Sign up at the [CollabKit dashboard](https://dash.collab-kit.com). This creates your organization and generates an API key.

## 2. Get Your API Key

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

<Note>
  Save both the `accountId` and `apiKey`. You'll need them to construct the Bearer token for all API calls.
</Note>

## 3. Create a Bearer Token

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

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

## 4. Create a Room

```bash theme={null}
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"}'
```

```json Response theme={null}
{
  "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:

```bash theme={null}
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\"
  }"
```

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

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

## 6. Install the Client SDK and Connect

```bash theme={null}
npm install @collab-kit/client @collab-kit/utils
```

```typescript theme={null}
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:

<CodeGroup>
  ```typescript Presence (Cursors) theme={null}
  // 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);
    }
  });
  ```

  ```typescript Broadcasts theme={null}
  // 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);
  });
  ```

  ```typescript Stores theme={null}
  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' },
  });
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Client SDK Reference" icon="code" href="/sdk/overview">
    Full API reference for all SDK modules.
  </Card>

  <Card title="Guides & Examples" icon="book-open" href="/guides/cursor-tracking">
    Build a cursor tracking experience and more.
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/api-reference/overview">
    Detailed HTTP API documentation.
  </Card>

  <Card title="Webhooks & Workflows" icon="webhook" href="/guides/webhooks-workflows">
    Automate server-side actions on events.
  </Card>
</CardGroup>