> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> CometChat Calling SDK v5 - Authentication for Flutter

Before users can make or receive calls, they must be authenticated with the CometChat Calls SDK. This guide covers the login and logout methods.

<Note>
  **Sample Users**

  CometChat provides 5 test users: `cometchat-uid-1`, `cometchat-uid-2`, `cometchat-uid-3`, `cometchat-uid-4`, and `cometchat-uid-5`.
</Note>

## Check Login Status

Before calling `login()`, check if a user is already logged in using `getLoggedInUser()`. The SDK maintains the session internally, so you only need to login once per user session.

```dart theme={null}
User? loggedInUser = await CometChatCalls.getLoggedInUser();

if (loggedInUser != null) {
  // User is already logged in
  debugPrint("User already logged in: ${loggedInUser.uid}");
} else {
  // No user logged in, proceed with login
}
```

The `getLoggedInUser()` method returns a `Future<User?>` — it resolves to a `User` object if a user is logged in, or `null` if no session exists.

## Login with UID and API Key

This method is suitable for development and testing. For production apps, use [Auth Token login](#login-with-auth-token) instead.

<Warning>
  **Security Notice**

  Using the API Key directly in client code is not recommended for production. Use Auth Token authentication for enhanced security.
</Warning>

```dart theme={null}
String uid = "cometchat-uid-1"; // Replace with your user's UID
String authKey = "AUTH_KEY"; // Replace with your Auth Key

User? loggedInUser = await CometChatCalls.getLoggedInUser();

if (loggedInUser == null) {
  CometChatCalls.login(
    uid: uid,
    authKey: authKey,
    onSuccess: (User user) {
      debugPrint("Login successful: ${user.uid}");
    },
    onError: (CometChatCallsException e) {
      debugPrint("Login failed: ${e.message}");
    },
  );
} else {
  // User already logged in
}
```

| Parameter   | Type                              | Description                                                  |
| ----------- | --------------------------------- | ------------------------------------------------------------ |
| `uid`       | String                            | The unique identifier of the user to login                   |
| `authKey`   | String                            | Your CometChat Auth Key                                      |
| `onSuccess` | Function(User)                    | Callback invoked on successful login with the logged-in user |
| `onError`   | Function(CometChatCallsException) | Callback invoked on login failure                            |

## Login with Auth Token

This is the recommended authentication method for production applications. The Auth Token is generated server-side, keeping your API Key secure.

### Auth Token Flow

1. User authenticates with your backend
2. Your backend calls the [CometChat Create Auth Token API](https://api-explorer.cometchat.com/reference/create-authtoken)
3. Your backend returns the Auth Token to the client
4. Client uses the Auth Token to login

```dart theme={null}
String authToken = "AUTH_TOKEN"; // Token received from your backend

CometChatCalls.loginWithAuthToken(
  authToken: authToken,
  onSuccess: (User user) {
    debugPrint("Login successful: ${user.uid}");
  },
  onError: (CometChatCallsException e) {
    debugPrint("Login failed: ${e.message}");
  },
);
```

| Parameter   | Type                              | Description                                                  |
| ----------- | --------------------------------- | ------------------------------------------------------------ |
| `authToken` | String                            | Auth Token generated via CometChat API                       |
| `onSuccess` | Function(User)                    | Callback invoked on successful login with the logged-in user |
| `onError`   | Function(CometChatCallsException) | Callback invoked on login failure                            |

## User Object

On successful login, the callback returns a `User` object containing user information:

| Property | Type   | Description                    |
| -------- | ------ | ------------------------------ |
| `uid`    | String | Unique identifier of the user  |
| `name`   | String | Display name of the user       |
| `avatar` | String | URL of the user's avatar image |
| `status` | String | User's online status           |

## Logout

Call `logout()` when the user signs out of your application. This clears the local session and disconnects from CometChat services.

```dart theme={null}
CometChatCalls.logout(
  onSuccess: (String message) {
    debugPrint("Logout successful");
  },
  onError: (CometChatCallsException e) {
    debugPrint("Logout failed: ${e.message}");
  },
);
```

## Error Handling

Common authentication errors:

| Error Code                | Description                              |
| ------------------------- | ---------------------------------------- |
| `ERROR_INVALID_UID`       | The provided UID is empty or invalid     |
| `ERROR_UID_WITH_SPACE`    | The UID contains spaces (not allowed)    |
| `ERROR_API_KEY_NOT_FOUND` | The API Key is missing or invalid        |
| `ERROR_BLANK_AUTHTOKEN`   | The Auth Token is empty                  |
| `ERROR_LOGIN_IN_PROGRESS` | A login operation is already in progress |