Skip to main content
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"
  }'
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.connect();
await client.join(); // User is now online
The JWT contains:
  • accountId — Your organization ID
  • userId — The user’s ID
  • roomId — The room ID
  • exp — Expiration (90 days from creation)