> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Manage users in your CometChat app — create, retrieve, update, and delete user accounts that power messaging and calling.

A **User** is the core identity in CometChat. Every person (or bot) that sends messages, joins groups, or makes calls must exist as a User. Users are identified by a unique `uid` that you assign during creation and cannot change afterward.

### How Users connect to other resources

* **Auth Tokens** — A User needs an auth token to log in via the SDK. You can generate one during creation (`withAuthToken: true`) or separately via the [Auth Tokens API](/rest-api/auth-tokens).
* **Groups** — Users can join up to 2,000 [Groups](/rest-api/groups) and participate in group messaging and calling.
* **Messages** — Users send and receive [Messages](/rest-api/messages) in 1-on-1 or group conversations.
* **Friends** — Users can add up to 1,000 [Friends](/rest-api/friends). Friendships are bidirectional.
* **Roles** — Users can be assigned a [Role](/rest-api/roles) that controls permissions. If no role is set, the default role applies.
* **Blocked Users** — Users can [block other users](/rest-api/blocked-users) to prevent all direct communication in both directions.

### Common workflow

1. [Create a User](/rest-api/users/create) with `withAuthToken: true` to get an auth token in the same call.
2. Use the auth token to initialize the CometChat SDK on the client.
3. The user can now [send messages](/rest-api/messages), [join groups](/rest-api/groups), and [make calls](/rest-api/calls-apis/overview).

<Info>
  UIDs are automatically converted to lowercase during creation. For example,
  `CometChat-UID-1` becomes `cometchat-uid-1`.
</Info>

### Available operations

| Operation | Method | Endpoint | Description |
| - | - | - | - |
| [List](/rest-api/users/list) | `GET` | `/users` | Retrieve a paginated list of users with filtering options |
| [Create](/rest-api/users/create) | `POST` | `/users` | Create a new user in your app |
| [Get](/rest-api/users/get) | `GET` | `/users/{uid}` | Retrieve a specific user's details |
| [Update](/rest-api/users/update) | `PUT` | `/users/{uid}` | Modify a user's profile (name, avatar, role, metadata) |
| [Delete](/rest-api/users/delete) | `DELETE` | `/users/{uid}` | Deactivate or permanently delete a user |
| [Deactivate](/rest-api/users/deactivate) | `DELETE` | `/users` | Temporarily disable users while preserving their data |
| [Reactivate](/rest-api/users/reactivate) | `PUT` | `/users` | Restore previously deactivated users |

### User properties

The following table lists the properties that the User object supports.

| Property | Type | Description |
| - | - | - |
| **uid** | string | **Required.** User's unique identifier. Max 100 characters. Alphanumeric with dashes and underscores only, no spaces. Case-insensitive and immutable after creation. |
| **name** | string | **Required.** Display name shown in chat interfaces and notifications. Max 100 characters. Supports all languages and emojis (UTF8mb4). |
| **avatar** | string | URL to the user's profile picture. Max 3,000 characters. CometChat stores the URL, not the image itself. Recommended size: 200×200 pixels. |
| **link** | string | URL to the user's profile page in your application. Max 3,000 characters. |
| **role** | string | Role assigned to the user. Must be created beforehand using the [Create Role API](/rest-api/roles/create). Defaults to the default role if not set. |
| **metadata** | object | JSON object for storing additional user information (e.g., email, phone, preferences). Max 5 KB. Use the `@private` key for sensitive data that should only be visible to the user themselves and via admin APIs. |
| **tags** | array of strings | Tags for categorizing and filtering users. Max 25 tags per user, 100 characters each (UTF8mb4). Useful for segmenting by department, location, or custom criteria. |
| **withAuthToken** | boolean | When `true` on creation, includes the auth token in the response — saving a separate API call. Only applicable during [Create](/rest-api/users/create). |
| **createdAt** | integer | UNIX timestamp indicating when the user was created. System-generated, read-only. |

### Error handling

When API calls fail, CometChat returns structured error responses. The most common errors for User operations:

| Error Code | Description |
| - | - |
| `AUTH_ERR_EMPTY_APIKEY` | API key is missing from the request headers |
| `AUTH_ERR_APIKEY_NOT_FOUND` | The provided API key is invalid |
| `AUTH_ERR_NO_ACCESS` | The API key doesn't have the required scope (e.g., using an authOnly key for a fullAccess operation) |
| `ERR_UID_NOT_FOUND` | The specified UID does not exist, or the user has been deactivated |

For the complete list of error codes, see [Error Guide](/articles/error-guide).

For all system limits (metadata size, tag counts, ID length, etc.), see [Properties and Constraints](/articles/properties-and-constraints).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.