Authentication and User Management

Create users, issue auth tokens, and log users into CometChat.

Create and Log In a User

Guide details

This guide provides a step-by-step guide on creating and logging in a user using the CometChat platform with authentication using the Authentication Token. Additionally, you will need to make sure you have initialized CometChat in your app prior to logging in the user.

Introduction

To log in a user, they must first be registered on the CometChat server. For first-time logins, the user needs to be created in CometChat. After this initial creation, we can generate an authentication token for the user.

This authentication token, created via the CometChat API, will be used on the front-end to log the user into the CometChat UI Kit, SDK, or Widget.

Once the user is successfully logged into CometChat, we can proceed to request or post any necessary data for the app.

Prerequisites

• CometChat App (You can create one via the CometChat Dashboard).
• CometChat UI Kit or SDK (Custom Widget as well).
• Your application: Front-end and Back-end / Server Side.

Create Chat User in CometChat

When a new user signs up in your app, create a matching CometChat user from your server using the Create User API. Pass withAuthToken: true to also mint a login token in the same call.

1. In your own sign-up flow, create the user in your database.
2. From your backend, call POST /v3/users with the user’s uid and name.
3. CometChat returns the created user (and an auth token when withAuthToken is set).
4. Return that auth token to your front-end to log the user in.

curl -X POST "https://<appId>.api-<region>.cometchat.io/v3/users" \
  -H "apikey: YOUR_REST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "cometchat-uid-1",
    "name": "Andrew Joseph",
    "withAuthToken": true
  }'

Call this from your server only — it requires the fullAccess REST API Key, which must never ship in client-side code. See REST API Authentication for key scopes.

The uid must be unique, ≤ 100 characters, alphanumeric with dashes (no spaces), and cannot be changed after creation. For the full field list and limits, see the Create User reference.

Then log the user into the SDK / UI Kit or Widget with the returned token:

// SDK
CometChat.login(authToken).then(user => { /* logged in */ });

// UI Kit
CometChatUIKit.loginWithAuthToken(authToken);

Log In an Existing User

The user already exists in CometChat, so you only need a fresh auth token each time they sign in to your app.

1. Authenticate the user with your own backend.
2. From your server, generate a token via the Create Auth Token API — POST /v3/users/{uid}/auth_tokens.
3. Return the token to your front-end.
4. Log in with CometChat.login(authToken) (SDK) or CometChatUIKit.loginWithAuthToken(authToken) (UI Kit). For the Widget Builder, see auth token–based login.

curl -X POST "https://<appId>.api-<region>.cometchat.io/v3/users/cometchat-uid-1/auth_tokens" \
  -H "apikey: YOUR_REST_API_KEY"

Auth token lifecycle

• Expiry: auth tokens do not expire by default, which keeps users signed in across devices. Generating a new token does not invalidate older ones on their own.
• Retention: CometChat keeps only the 100 most recent auth tokens per user; older tokens are automatically archived and invalidated.
• Revoking sessions: delete one token with Delete Auth Token, or sign a user out everywhere with Flush Auth Tokens (DELETE /v3/users/{uid}/auth_tokens).

Migrate Existing Users to CometChat

If you need to migrate existing users in bulk, see Data Import and Migration.