> ## 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.

# Create User

> Create a user in a room and get a JWT token for WebSocket auth.

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

<ParamField body="name" type="string" required>
  Display name for the user.
</ParamField>

<ParamField body="roomId" type="string" required>
  The room to add the user to.
</ParamField>

<ParamField body="profilePicture" type="string">
  URL of the user's avatar image.
</ParamField>

<ParamField body="customId" type="string">
  Optional custom identifier for external system correlation. Must be unique within the room.
</ParamField>

## Response

<ResponseField name="user" type="CollabKitUser">
  The created user. See [`CollabKitUser`](/types/core#collabkituser).
</ResponseField>

<ResponseField name="token" type="string">
  JWT token for WebSocket authentication. Valid for 90 days. Pass this to the `CollabKitClient` constructor.
</ResponseField>

## Example

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

  ```typescript JavaScript theme={null}
  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
  ```
</CodeGroup>

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

<Tip>
  The user starts with `"offline"` status. They become `"online"` when the client SDK calls `join()`.
</Tip>

## Using the JWT Token

Pass the returned `token` to the client SDK:

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