Authentication - CometChat Docs

Quick Reference for AI Agents & Developers

Login with Auth Key: CometChat.login(UID:authKey:onSuccess:onError:) — for development/testing
Login with Auth Token: CometChat.login(authToken:onSuccess:onError:) — for production (generate token server-side)
Logout: CometChat.logout(onSuccess:onError:)
Get logged-in user: CometChat.getLoggedInUser()
Related: Setup · User Management · Key Concepts

Create User

Before you log in a user, you must add the user to CometChat.

For proof of concept/MVPs: Create the user using the CometChat Dashboard.
For production apps: Use the CometChat Create User API to create the user when your user signs up in your app.

Sample UsersWe have setup 5 users for testing having UIDs: cometchat-uid-1, cometchat-uid-2, cometchat-uid-3, cometchat-uid-4 and cometchat-uid-5.

Once initialization is successful, you will need to log the user into CometChat using the login() method. We recommend you call the CometChat login method once your user logs into your app. The login method needs to be called only once but the getLoggedInUser() needs to be checked every-time when the app starts and if it returns null then you need to call the login method.

This straightforward authentication method is ideal for proof-of-concept (POC) development or during the early stages of application development. For production environments, however, we strongly recommend using an AuthToken instead of an Auth Key to ensure enhanced security. The login method needs to be called in the following scenarios:

When the user is logging into the App for the first time.
If the CometChat.getLoggedInUser() function returns nil.

Swift
Objective C

let uid = "cometchat-uid-1"
let authKey = "AUTH_KEY"

if CometChat.getLoggedInUser() == nil {

	CometChat.login(UID: uid, authKey: authKey, onSuccess: { (user) in

  	print("Login successful : " + user.stringValue())

	}) { (error) in

  	print("Login failed with error: " + error.errorDescription);

	}

}

NSString *uid = @"cometchat-uid-1";
NSString *authKey = @"YOUR_AUTH_KEY";

[CometChat loginWithUID:uid authKey:authKey onSuccess:^(User * user) {

    NSLog(@"Login successful : %@",[user stringValue]);

} onError:^(CometChatException * error) {

    NSLog(@"Login failed with error:%@",[error errorDescription]);

}];

Parameter	Description
UID	The UID of the user that you would like to login
authKey	CometChat Auth Key

The login() method returns the User object containing all the information of the logged-in user.

Sample Payloads

Request
Success Response
Error Response (Invalid UID)
Error Response (Invalid AuthKey)

Method: CometChat.login(UID:authKey:)

Parameter	Type	Value
UID	`String`	`"cometchat-uid-2"`
authKey	`String`	`"537ab75a0d76f93a811d0cb390a3a0de936b3ed0"`

Object Type: User

Parameter	Type	Value
uid	`String`	`"cometchat-uid-2"`
name	`String`	`"George Alan"`
avatar	`String`	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	`String?`	`nil`
role	`String`	`"moderator"`
status	`CometChat.UserStatus`	`1` (`.offline`)
statusMessage	`String?`	`nil`
lastActiveAt	`Double`	`1771912504.0`
hasBlockedMe	`Bool`	`false`
blockedByMe	`Bool`	`false`
metadata	`[String: Any]`	`[:]` (empty dictionary)
deactivatedAt	`Double`	`0.0`

Request Parameters:

Parameter	Type	Value
UID	`String`	`"non_existent_user_xyz_12345"`
authKey	`String`	`"537ab75a0d76f93a811d0cb390a3a0de936b3ed0"`

Error Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERR_UID_NOT_FOUND"`
errorDescription	`String`	`"The UID non_existent_user_xyz_12345 does not exist, so please make sure you have created a user with UID non_existent_user_xyz_12345."`

Request Parameters:

Parameter	Type	Value
UID	`String`	`"cometchat-uid-2"`
authKey	`String`	`"invalid_auth_key_xyz"`

Error Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"AUTH_ERR_APIKEY_NOT_FOUND"`
errorDescription	`String`	`"The key inval**********y_xyz does not exist. Please use correct apiKey."`

This advanced authentication procedure does not use the Auth Key directly in your client code thus ensuring safety.

Create a user via the CometChat API when the user signs up in your app.
Create an Auth Token via the CometChat API for the new user and save the token in your database.
Load the Auth Token in your client and pass it to the login() method.

The login method needs to be called in the following scenarios:

When the user is logging into the App for the first time.
If the CometChat.getLoggedInUser() function returns nil.

Swift
Objective C

let authToken = "YOUR_AUTH_TOKEN";

if CometChat.getLoggedInUser() == nil {

  CometChat.login(authToken: authToken , onSuccess: { (user) in

    print("Login successful : " + user.stringValue())

  }) { (error) in

    print("Login failed with error: " + error.errorDescription);
  }

}

NSString *authToken = @"YOUR_AUTH_TOKEN";

[CometChat loginWithAuthToken:authToken onSuccess:^(User * user) {

    __ Login Successful
    NSLog(@"Login Successful : %@",[user stringValue]);

} onError:^(CometChatException * error) {

    __ Login error
    NSLog(@"Login failed with exception: %@",[error errorDescription]);

}];

Parameter	Description
authToken	Auth Token of the user you would like to login

The login() method returns the User object containing all the information of the logged-in user.

Sample Payloads

Request
Success Response
Error Response (Invalid Token)

Method: CometChat.login(authToken:)

Parameter	Type	Value
authToken	`String`	`"cometchat-uid-2_1770120517a02ff84f63e515ece9895ebe2481df"`

Object Type: User

Parameter	Type	Value
uid	`String`	`"cometchat-uid-2"`
name	`String`	`"George Alan"`
avatar	`String`	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	`String?`	`nil`
role	`String`	`"moderator"`
status	`CometChat.UserStatus`	`1` (`.offline`)
statusMessage	`String?`	`nil`
lastActiveAt	`Double`	`1771912817.0`
hasBlockedMe	`Bool`	`false`
blockedByMe	`Bool`	`false`
metadata	`[String: Any]`	`[:]` (empty dictionary)
deactivatedAt	`Double`	`0.0`

Request Parameters:

Parameter	Type	Value
authToken	`String`	`"invalid_auth_token_xyz_12345"`

Error Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"AUTH_ERR_AUTH_TOKEN_NOT_FOUND"`
errorDescription	`String`	`"The auth token inval******************12345 does not exist. Please make sure you are logged in and have a valid auth token or try login again."`

Logout

You can use the logout() method to log out the user from CometChat.

Swift
Objective C

CometChat.logout(onSuccess: { (response) in

  print("Logout successfully.")

}) { (error) in

  print("logout failed with error: " + error.errorDescription);
}

[CometChat logoutOnSuccess:^(NSString * response) {

    __ Logout Success
    NSLog(@"%@", response);

} onError:^(CometChatException * error) {

    __ Logout error
    NSLog(@"%@",[error errorDescription]);
}];

Sample Payloads

Request
Success Response
Error Response

Method: CometChat.logout()

Parameter	Type	Value
—	—	No request parameters

Response Type: String

Parameter	Type	Value
response	`String`	`"User logged out successfully."`

Error Object Type: CometChatException

Parameter	Type	Value
errorCode	`String`	`"ERR_NOT_LOGGED_IN"`
errorDescription	`String`	`"Cannot logout - no user is currently logged in."`

Helper Methods

getLoggedInUser()

Use CometChat.getLoggedInUser() to check if a user is currently logged in. This method returns the logged-in User object or nil if no user is logged in.

Swift

if let user = CometChat.getLoggedInUser() {
    print("User is logged in: \(user.uid ?? "")")
} else {
    print("No user logged in")
}

Sample Payloads

Response (No User Logged In)
Response (User Logged In)

Method: CometChat.getLoggedInUser()Return Type: User?

Parameter	Type	Value
return	`User?`	`nil` (no user logged in)

Method: CometChat.getLoggedInUser()Return Type: User

Parameter	Type	Value
uid	`String`	`"cometchat-uid-2"`
name	`String`	`"George Alan"`
avatar	`String`	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	`String?`	`nil`
role	`String`	`"moderator"`
status	`CometChat.UserStatus`	`1` (`.offline`)
statusMessage	`String?`	`nil`
lastActiveAt	`Double`	`1771912817.0`
hasBlockedMe	`Bool`	`false`
blockedByMe	`Bool`	`false`
metadata	`[String: Any]`	`[:]` (empty dictionary)
deactivatedAt	`Double`	`0.0`

Object Structures

User Object

The User object represents a CometChat user and contains all user-related information.

Parameter	Type	Description
uid	`String?`	Unique user identifier assigned during user creation
name	`String?`	Display name of the user
avatar	`String?`	Avatar image URL
link	`String?`	Profile link URL
role	`String?`	User role (e.g., `"default"`, `"admin"`, `"moderator"`)
metadata	`[String: Any]?`	Custom metadata dictionary for storing additional user data
status	`CometChat.UserStatus`	User status: `.online` (0), `.offline` (1), or `.available`
statusMessage	`String?`	Custom status message set by the user
lastActiveAt	`Double`	Unix timestamp of last activity
hasBlockedMe	`Bool`	`true` if this user has blocked the logged-in user
blockedByMe	`Bool`	`true` if the logged-in user has blocked this user
deactivatedAt	`Double`	Unix timestamp when user was deactivated (`0.0` if active)
tags	`[String]`	Array of tags associated with the user
authToken	`String?`	Authentication token for the session
createdAt	`Double?`	Unix timestamp of account creation
updatedAt	`Double?`	Unix timestamp of last profile update

CometChatException Object

The CometChatException object represents an error returned by the SDK.

Parameter	Type	Description
errorCode	`String`	Unique error code identifier for programmatic handling
errorDescription	`String`	Human-readable error message
details	`String?`	Additional context or troubleshooting information

Common Error Codes

Error Code	Description	Resolution
`ERR_UID_NOT_FOUND`	User with specified UID does not exist	Create user first via API or Dashboard
`ERR_INVALID_API_KEY`	Invalid Auth Key provided	Verify Auth Key from Dashboard
`AUTH_ERR_APIKEY_NOT_FOUND`	Auth Key does not exist	Verify Auth Key from Dashboard
`AUTH_ERR_AUTH_TOKEN_NOT_FOUND`	Auth Token does not exist or is invalid	Generate new Auth Token
`ERR_USER_DEACTIVATED`	User account is deactivated	Reactivate user via Dashboard
`ERR_NOT_LOGGED_IN`	No user is currently logged in	Call login() first
`ERR_SDK_NOT_INITIALIZED`	SDK not initialized	Call CometChat.init() first
`ERR_NETWORK_ERROR`	Network connectivity issue	Check internet connection and retry

CometChatLoginDelegate

The CometChatLoginDelegate protocol allows you to listen for authentication events (login/logout) across your application. This is useful for updating UI state, managing session data, or triggering side effects when authentication status changes.

Setup

To receive login/logout events, conform to CometChatLoginDelegate and register your class:

Swift

import CometChatSDK

class AuthManager: CometChatLoginDelegate {
    
    init() {
        // Register as login delegate
        CometChat.loginDelegate = self
    }
    
    // MARK: - CometChatLoginDelegate Methods
    
    func onLoginSuccess(user: User) {
        print("Login successful for user: \(user.uid ?? "")")
    }
    
    func onLoginFailed(error: CometChatException?) {
        print("Login failed: \(error?.errorDescription ?? "Unknown error")")
    }
    
    func onLogoutSuccess() {
        print("Logout successful")
    }
    
    func onLogoutFailed(error: CometChatException?) {
        print("Logout failed: \(error?.errorDescription ?? "Unknown error")")
    }
}

Important Considerations

The delegate must be set before calling login() or logout() to receive events
Only one delegate can be registered at a time; setting a new delegate replaces the previous one
The delegate methods are called on the main thread
SDK must be initialized before setting the delegate
Delegate is not persisted across app restarts; re-register on app launch

onLoginSuccess(user: User)

Called when a user successfully logs in via CometChat.login().

Sample Payloads

Request
Success Response
Error Response

Trigger: CometChat.login(UID:authKey:) or CometChat.login(authToken:)

Parameter	Type	Value
UID	`String`	`"cometchat-uid-2"`
authKey	`String`	`"AUTH_KEY"`

Delegate Method: onLoginSuccess(user: User)Parameter Type: User

Parameter	Type	Value
uid	`String`	`"cometchat-uid-2"`
name	`String`	`"George Alan"`
avatar	`String`	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"`
link	`String?`	`nil`
role	`String`	`"moderator"`
metadata	`[String: Any]`	`[:]` (empty dictionary)
status	`CometChat.UserStatus`	`1` (`.offline`)
statusMessage	`String?`	`nil`
lastActiveAt	`Double`	`1771913988.0`
hasBlockedMe	`Bool`	`false`
blockedByMe	`Bool`	`false`
tags	`[String]`	`[]` (empty array)
deactivatedAt	`Double`	`0.0`

Edge Cases & Considerations

Scenario	Behavior
Delegate not set	Method will not be called even on successful login
SDK not initialized	Login will fail before delegate is called
Already logged in	Calling login again returns existing user; delegate is still called
Network disconnection after login	Login succeeds; connection listener handles reconnection
User deactivated after login	User object contains `deactivatedAt` timestamp

onLoginFailed(error: CometChatException?)

Called when a login attempt fails.

Sample Payloads

Request
Success Response
Error Response

Trigger: CometChat.login(UID:authKey:) with invalid credentials

Parameter	Type	Value
UID	`String`	`"non_existent_user_xyz_99999"`
authKey	`String`	`"AUTH_KEY"`

Delegate Method: onLoginFailed(error: CometChatException?)Parameter Type: CometChatException?

Parameter	Type	Value
errorCode	`String`	`"ERR_UID_NOT_FOUND"`
errorDescription	`String`	`"The UID non_existent_user_xyz_99999 does not exist, so please make sure you have created a user with UID non_existent_user_xyz_99999."`

Edge Cases & Considerations

Scenario	Behavior
`error` parameter is nil	Rare; indicates internal SDK error - log and retry
Multiple rapid login failures	Implement exponential backoff to avoid rate limiting
Network timeout	`ERR_NETWORK_ERROR` returned; safe to retry
Invalid credentials cached	Clear stored credentials and prompt user to re-enter

onLogoutSuccess()

Called when a user successfully logs out via CometChat.logout().

Sample Payloads

Request
Success Response
Error Response

Trigger: CometChat.logout()

Parameter	Type	Value
—	—	No request parameters

Delegate Method: onLogoutSuccess()Return Type: Void (no payload)

Parameter	Type	Value
—	—	This delegate method receives no parameters

Success is indicated by the method being called. The CometChat.logout() callback receives: "User logged out successfully."

Edge Cases & Considerations

Scenario	Behavior
Logout while offline	May fail with network error; local session persists
Logout during active call	Call is terminated before logout completes
Multiple logout calls	Subsequent calls may return `ERR_NOT_LOGGED_IN`
App killed during logout	Session may persist; check on next app launch

onLogoutFailed(error: CometChatException?)

Called when a logout attempt fails.

Sample Payloads

Request
Success Response
Error Response

Trigger: CometChat.logout() when no user is logged in

Parameter	Type	Value
—	—	No request parameters

Delegate Method: onLogoutFailed(error: CometChatException?)Parameter Type: CometChatException?

Parameter	Type	Value
errorCode	`String`	`"ERR_NOT_LOGGED_IN"`
errorDescription	`String`	`"Cannot logout - no user is currently logged in."`

Edge Cases & Considerations

Scenario	Behavior
`error` parameter is nil	Rare; treat as unknown error
Logout fails due to network	Consider force local logout option
SDK crashes during logout	Local session may persist; handle on next launch

Complete Implementation Example

Full CometChatLoginDelegate Implementation

import UIKit
import CometChatSDK

class AuthenticationManager: CometChatLoginDelegate {
    
    static let shared = AuthenticationManager()
    
    private init() {
        // Register as login delegate
        CometChat.loginDelegate = self
    }
    
    // MARK: - CometChatLoginDelegate
    
    func onLoginSuccess(user: User) {
        print("✅ Login successful")
        print("   UID: \(user.uid ?? "N/A")")
        print("   Name: \(user.name ?? "N/A")")
        print("   Status: \(user.status == .online ? "Online" : "Offline")")
        
        // Store user session
        if let authToken = user.authToken {
            KeychainManager.save(key: "auth_token", value: authToken)
        }
        
        // Post notification for UI updates
        NotificationCenter.default.post(
            name: .userDidLogin,
            object: nil,
            userInfo: ["user": user]
        )
    }
    
    func onLoginFailed(error: CometChatException?) {
        print("❌ Login failed")
        
        guard let error = error else {
            print("   Unknown error")
            return
        }
        
        print("   Code: \(error.errorCode)")
        print("   Message: \(error.errorDescription)")
        
        // Post notification for UI updates
        NotificationCenter.default.post(
            name: .userLoginFailed,
            object: nil,
            userInfo: ["error": error]
        )
    }
    
    func onLogoutSuccess() {
        print("✅ Logout successful")
        
        // Clear stored credentials
        KeychainManager.delete(key: "auth_token")
        UserDefaults.standard.removeObject(forKey: "current_user")
        
        // Post notification for UI updates
        NotificationCenter.default.post(name: .userDidLogout, object: nil)
    }
    
    func onLogoutFailed(error: CometChatException?) {
        print("❌ Logout failed")
        
        if let error = error {
            print("   Code: \(error.errorCode)")
            print("   Message: \(error.errorDescription)")
            
            // If not logged in, treat as success
            if error.errorCode == "ERR_NOT_LOGGED_IN" {
                onLogoutSuccess()
                return
            }
        }
        
        // Post notification for UI updates
        NotificationCenter.default.post(
            name: .userLogoutFailed,
            object: nil,
            userInfo: error != nil ? ["error": error!] : nil
        )
    }
}

// MARK: - Notification Names
extension Notification.Name {
    static let userDidLogin = Notification.Name("userDidLogin")
    static let userLoginFailed = Notification.Name("userLoginFailed")
    static let userDidLogout = Notification.Name("userDidLogout")
    static let userLogoutFailed = Notification.Name("userLogoutFailed")
}

Section Validation

Documentation Self-Sufficiency Check

Criteria	Status
All delegate methods documented	✅ Complete
Sample Payloads (Request/Success/Error) in tabular format	✅ Complete for all methods
Property tables with types	✅ Complete
Common error codes	✅ Documented with resolutions
Edge cases documented	✅ For all methods
Setup instructions	✅ Complete
Complete implementation example	✅ Included
Cross-references with links	✅ Added

Conclusion: This section is now self-sufficient. A developer can implement CometChatLoginDelegate without guessing or requiring additional SDK exploration.

​Create User

​Login using Auth Key

​Login using Auth Token

​Logout

​Helper Methods

​getLoggedInUser()

​Object Structures

​User Object

​CometChatException Object

​Common Error Codes

​CometChatLoginDelegate

​Setup

​onLoginSuccess(user: User)

​onLoginFailed(error: CometChatException?)

​onLogoutSuccess()

​onLogoutFailed(error: CometChatException?)

​Complete Implementation Example

​Section Validation

Create User

Login using Auth Key

Login using Auth Token

Logout

Helper Methods

getLoggedInUser()

Object Structures

User Object

CometChatException Object

Common Error Codes

CometChatLoginDelegate

Setup

onLoginSuccess(user: User)

onLoginFailed(error: CometChatException?)

onLogoutSuccess()

onLogoutFailed(error: CometChatException?)

Complete Implementation Example

Section Validation