Create User

Create a new user in a room. Returns the user details and a JWT token that the client SDK uses for WebSocket authentication.

Endpoint

POST /v1/accounts/:accountId/users

Authentication

Bearer token required.

Request Body

name

string

required

Display name for the user.

roomId

string

required

The room to add the user to.

profilePicture

string

URL of the user’s avatar image.

customId

string

Optional custom identifier for external system correlation. Must be unique within the room.

Response

user

CollabKitUser

The created user. See CollabKitUser.

token

string

JWT token for WebSocket authentication. Valid for 90 days. Pass this to the CollabKitClient constructor.

Example

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": "c3003c93-60cf-4184-b85f-20be14d26dac",
    "profilePicture": "https://example.com/alice.png",
    "customId": "alice-001"
  }'

const res = await fetch(`https://api.collab-kit.com/v1/accounts/${accountId}/users`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Alice',
    roomId: 'c3003c93-60cf-4184-b85f-20be14d26dac',
    profilePicture: 'https://example.com/alice.png',
    customId: 'alice-001',
  }),
});
const { data } = await res.json();
// data.token is the JWT for the client SDK

Response (201)

{
  "type": "response",
  "success": true,
  "description": "User created",
  "data": {
    "user": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "room_id": "c3003c93-60cf-4184-...",
      "name": "Alice",
      "profile_picture": "https://example.com/alice.png",
      "custom_id": "alice-001",
      "status": "offline",
      "created_at": "2026-05-29T10:05:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "error": null
}

The user starts with "offline" status. They become "online" when the client SDK calls join().

Using the JWT Token

Pass the returned token to the client SDK:

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

const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: data.token, // JWT from POST /v1/accounts/:accountId/users
});

await client.join(); // User is now online as an editor by default
// await client.join({ role: 'viewer' });

The JWT contains:

accountId — Your organization ID
userId — The user’s ID
roomId — The room ID
exp — Expiration (90 days from creation)

Overview

Rooms

Users

Storage

Webhooks

Workflows

Endpoint

Authentication

Request Body

Response

Example

Using the JWT Token

​Endpoint

​Authentication

​Request Body

​Response

​Example

​Using the JWT Token

Endpoint

Authentication

Request Body

Response

Example

Using the JWT Token