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

# User Management

> Create, update, and manage CometChat users programmatically using the Flutter SDK. Includes user creation, profile updates, and the User class reference.

<Accordion title="AI Integration Quick Reference">
  ```dart theme={null}
  // Create a user
  User user = User(uid: "user1", name: "Kevin");
  CometChat.createUser(user, "AUTH_KEY", onSuccess: (User user) {
    debugPrint("User created: ${user.name}");
  }, onError: (CometChatException e) {
    debugPrint("Error: ${e.message}");
  });

  // Update a user (requires API Key)
  User updatedUser = User(uid: "user1", name: "Kevin Fernandez");
  CometChat.updateUser(updatedUser, "AUTH_KEY", onSuccess: (User user) {
    debugPrint("User updated: ${user.name}");
  }, onError: (CometChatException e) {
    debugPrint("Error: ${e.message}");
  });

  // Update logged-in user (no auth key needed)
  User currentUser = User(name: "New Name");
  CometChat.updateCurrentUserDetails(currentUser, onSuccess: (User user) {
    debugPrint("User updated: ${user.name}");
  }, onError: (CometChatException e) {
    debugPrint("Error: ${e.message}");
  });
  ```

  **Note:** User creation/deletion should ideally happen on your backend via the [REST API](https://api-explorer.cometchat.com).
</Accordion>

Users must exist in CometChat before they can log in. This page covers creating, updating, and deleting users. All methods that return user data return a [`User`](/sdk/reference/entities#user) object.

The typical flow:

1. User registers in your app → Create user in CometChat
2. User logs into your app → [Log user into CometChat](/sdk/flutter/authentication-overview)

<Note>
  User deletion is only available via the [REST API](https://api-explorer.cometchat.com/reference/delete-user) — there is no client-side SDK method for it.
</Note>

## Creating a User

User creation should ideally happen on your backend via the [REST API](https://api-explorer.cometchat.com/reference/creates-user).

<Warning>
  **Security:** Never expose your `Auth Key` in client-side production code. User creation and updates using `Auth Key` should ideally happen on your backend server. Use client-side creation only for prototyping or development.
</Warning>

For client-side creation (development only), use `createUser()`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String authKey = "AUTH_KEY"; // Replace with the auth key of app
    User user = User(uid: "usr1", name: "Kevin"); // Replace with name and uid of user

    CometChat.createUser(user, authKey, onSuccess: (User user) {
      debugPrint("Create User successful $user");
    }, onError: (CometChatException e) {
      debugPrint("Create User Failed with exception ${e.message}");
    });
    ```
  </Tab>
</Tabs>

### Parameters

| Parameter   | Type                                 | Description                                                                                                     |
| ----------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `user`      | `User`                               | A `User` object containing the details of the user to be created. The `uid` and `name` fields are **required**. |
| `authKey`   | `String`                             | Your CometChat Auth Key. Use only for development — never expose in production client code.                     |
| `onSuccess` | `Function(User user)`                | Callback triggered on successful user creation, returning the created `User` object.                            |
| `onError`   | `Function(CometChatException excep)` | Callback triggered on failure, returning a `CometChatException` with error details.                             |

Returns a [`User`](/sdk/reference/entities#user) object. See [User Class](#user-class) for all available fields.

<Accordion title="Response">
  **On Success** — A `User` object containing all details of the created user:

  <span id="create-user-object" style={{scrollMarginTop: '100px'}} />

  **User Object:**

  | Parameter       | Type    | Description                                    | Sample Value |
  | --------------- | ------- | ---------------------------------------------- | ------------ |
  | `uid`           | string  | Unique identifier of the user                  | `"usr1"`     |
  | `name`          | string  | Display name of the user                       | `"Kevin"`    |
  | `link`          | string  | Profile link                                   | `null`       |
  | `avatar`        | string  | Avatar URL                                     | `null`       |
  | `metadata`      | object  | Custom metadata                                | `{}`         |
  | `status`        | string  | Online status                                  | `"offline"`  |
  | `role`          | string  | User role                                      | `"default"`  |
  | `statusMessage` | string  | Status message                                 | `null`       |
  | `tags`          | array   | List of tags associated with the user          | `[]`         |
  | `hasBlockedMe`  | boolean | Whether this user has blocked the current user | `false`      |
  | `blockedByMe`   | boolean | Whether the current user has blocked this user | `false`      |
  | `lastActiveAt`  | number  | Epoch timestamp of last activity               | `0`          |
</Accordion>

<Accordion title="Error">
  | Parameter | Type   | Description                  | Sample Value                                 |
  | --------- | ------ | ---------------------------- | -------------------------------------------- |
  | `code`    | string | Error code identifier        | `"ERR_UID_NOT_FOUND"`                        |
  | `message` | string | Human-readable error message | `"The specified UID does not exist."`        |
  | `details` | string | Additional technical details | `"Please provide a valid UID for the user."` |
</Accordion>

<Warning>
  UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed.
</Warning>

## Updating a User

Like creation, user updates should ideally happen on your backend via the [REST API](https://api-explorer.cometchat.com/reference/update-user).

For client-side updates (development only), use `updateUser()`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    String apiKey = "AUTH_KEY"; // Replace with the auth key of app
    User user = User(uid: "usr1", name: "Kevin Fernandez");

    CometChat.updateUser(user, apiKey, onSuccess: (User user) {
      debugPrint("User updated: $user");
    }, onError: (CometChatException e) {
      debugPrint("Update User Failed with exception ${e.message}");
    });
    ```
  </Tab>
</Tabs>

Ensure the [`User`](/sdk/reference/entities#user) object has the correct `UID` set.

### Parameters

| Parameter   | Type                                 | Description                                                                                 |
| ----------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `user`      | `User`                               | A `User` object with the `uid` of the user to update and the fields to change.              |
| `apiKey`    | `String`                             | Your CometChat Auth Key. Use only for development — never expose in production client code. |
| `onSuccess` | `Function(User retUser)`             | Callback triggered on successful update, returning the updated `User` object.               |
| `onError`   | `Function(CometChatException excep)` | Callback triggered on failure, returning a `CometChatException` with error details.         |

Returns a [`User`](/sdk/reference/entities#user) object. See [User Class](#user-class) for all available fields.

<Accordion title="Response">
  **On Success** — A `User` object containing all details of the updated user:

  | Parameter       | Type    | Description                                    | Sample Value        |
  | --------------- | ------- | ---------------------------------------------- | ------------------- |
  | `uid`           | string  | Unique identifier of the user                  | `"usr1"`            |
  | `name`          | string  | Display name of the user                       | `"Kevin Fernandez"` |
  | `link`          | string  | Profile link                                   | `null`              |
  | `avatar`        | string  | Avatar URL                                     | `null`              |
  | `metadata`      | object  | Custom metadata                                | `{}`                |
  | `status`        | string  | Online status                                  | `"offline"`         |
  | `role`          | string  | User role                                      | `"default"`         |
  | `statusMessage` | string  | Status message                                 | `null`              |
  | `tags`          | array   | List of tags associated with the user          | `[]`                |
  | `hasBlockedMe`  | boolean | Whether this user has blocked the current user | `false`             |
  | `blockedByMe`   | boolean | Whether the current user has blocked this user | `false`             |
  | `lastActiveAt`  | number  | Epoch timestamp of last activity               | `0`                 |
</Accordion>

<Accordion title="Error">
  | Parameter | Type   | Description                  | Sample Value                                 |
  | --------- | ------ | ---------------------------- | -------------------------------------------- |
  | `code`    | string | Error code identifier        | `"ERR_UID_NOT_FOUND"`                        |
  | `message` | string | Human-readable error message | `"The specified UID does not exist."`        |
  | `details` | string | Additional technical details | `"Please provide a valid UID for the user."` |
</Accordion>

## Updating Logged-in User

Use `updateCurrentUserDetails()` to update the current user without an Auth Key. Note: You cannot update the user's role with this method.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    User user = User(name: 'Updated Name');

    CometChat.updateCurrentUserDetails(user, onSuccess: (User updatedUser) {
      debugPrint("Updated User: $updatedUser");
    }, onError: (CometChatException e) {
      debugPrint("Updated User exception : ${e.message}");
    });
    ```
  </Tab>
</Tabs>

### Parameters

| Parameter   | Type                                 | Description                                                                                           |
| ----------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `user`      | `User`                               | A `User` object with the fields to update. The `uid` is ignored — only the logged-in user is updated. |
| `onSuccess` | `Function(User retUser)`             | Callback triggered on successful update, returning the updated `User` object.                         |
| `onError`   | `Function(CometChatException excep)` | Callback triggered on failure, returning a `CometChatException` with error details.                   |

The method returns a [`User`](/sdk/reference/entities#user) object.

<Accordion title="Response">
  **On Success** — A `User` object containing all details of the updated user:

  <span id="update-user-object" style={{scrollMarginTop: '100px'}} />

  **User Object:**

  | Parameter       | Type    | Description                                    | Sample Value                                                            |
  | --------------- | ------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
  | `uid`           | string  | Unique identifier of the user                  | `"cometchat-uid-1"`                                                     |
  | `name`          | string  | Display name of the user                       | `"Updated Name"`                                                        |
  | `link`          | string  | Profile link                                   | `null`                                                                  |
  | `avatar`        | string  | Avatar URL                                     | `"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp"` |
  | `metadata`      | object  | Custom metadata                                | `{}`                                                                    |
  | `status`        | string  | Online status                                  | `"online"`                                                              |
  | `role`          | string  | User role                                      | `"default"`                                                             |
  | `statusMessage` | string  | Status message                                 | `null`                                                                  |
  | `tags`          | array   | List of tags associated with the user          | `[]`                                                                    |
  | `hasBlockedMe`  | boolean | Whether this user has blocked the current user | `false`                                                                 |
  | `blockedByMe`   | boolean | Whether the current user has blocked this user | `false`                                                                 |
  | `lastActiveAt`  | number  | Epoch timestamp of last activity               | `1745554700`                                                            |
</Accordion>

<Accordion title="Error">
  | Parameter | Type   | Description                  | Sample Value                                 |
  | --------- | ------ | ---------------------------- | -------------------------------------------- |
  | `code`    | string | Error code identifier        | `"ERR_UID_NOT_FOUND"`                        |
  | `message` | string | Human-readable error message | `"The specified UID does not exist."`        |
  | `details` | string | Additional technical details | `"Please provide a valid UID for the user."` |
</Accordion>

By using the `updateCurrentUserDetails()` method one can only update the logged-in user irrespective of the UID passed. Also, it is not possible to update the role of a logged-in user.

## Deleting a User

User deletion is only available via the [REST API](https://api-explorer.cometchat.com/reference/delete-user).

## User Class

| Field         | Editable                                            | Information                                                          |
| ------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
| uid           | specified on user creation. Not editable after that | Unique identifier of the user                                        |
| name          | Yes                                                 | Display name of the user                                             |
| avatar        | Yes                                                 | URL to profile picture of the user                                   |
| link          | Yes                                                 | URL to profile page                                                  |
| role          | Yes                                                 | User role of the user for role based access control                  |
| metadata      | Yes                                                 | Additional information about the user as JSON                        |
| status        | No                                                  | Status of the user. Could be either online/offline                   |
| statusMessage | Yes                                                 | Any custom status message that needs to be set for a user            |
| lastActiveAt  | No                                                  | The unix timestamp of the time the user was last active.             |
| hasBlockedMe  | No                                                  | A boolean that determines if the user has blocked the logged in user |
| blockedByMe   | No                                                  | A boolean that determines if the logged in user has blocked the user |
| tags          | Yes                                                 | A list of tags to identify specific users                            |

## Next Steps

<CardGroup cols={2}>
  <Card title="Retrieve Users" icon="users" href="/sdk/flutter/retrieve-users">
    Fetch and filter user lists with pagination.
  </Card>

  <Card title="User Presence" icon="circle-dot" href="/sdk/flutter/user-presence">
    Monitor real-time online/offline status.
  </Card>

  <Card title="Block Users" icon="ban" href="/sdk/flutter/block-users">
    Block and unblock users.
  </Card>

  <Card title="Authentication" icon="key" href="/sdk/flutter/authentication-overview">
    Log users into CometChat.
  </Card>
</CardGroup>