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

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


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