Skip to main content
All CometChat REST API requests must be authenticated using an API key passed in the apikey HTTP header.
Calls APIs use a different base URL: https://{appId}.call-{region}.cometchat.io/v3 (note call- instead of api-). Authentication still uses the apikey header.
Management APIs use a different authentication mechanism — key and secret headers, not the apikey header. See the Management APIs overview for details.
curl -X GET "https://apimgmt.cometchat.io/apps" \
  -H "key: YOUR_MANAGEMENT_KEY" \
  -H "secret: YOUR_MANAGEMENT_SECRET"

​
API Key Scopes

CometChat supports two API key scopes:
ScopeDashboard NamePermissions
fullAccessREST API KeyAll REST API operations: create/update/delete users, groups, messages, manage settings, etc. Use server-side only.
authOnlyAuth KeyCan only create users and generate auth tokens. Intended for quick demos and prototyping.
Never expose a fullAccess (REST API Key) in client-side code. Keep it on your server only.The authOnly (Auth Key) is for demos only. In production, generate auth tokens from your backend during your app’s own authentication flow.

​
Making Authenticated Requests

Include the API key in the apikey header (all lowercase): 
curl -X GET "https://<appId>.api-<region>.cometchat.io/v3/users" \
  -H "apikey: YOUR_REST_API_KEY"
The HTTP header name is apikey (lowercase). In JSON response bodies, the property is apiKey (camelCase). HTTP headers are case-insensitive by spec; JSON properties are case-sensitive.

​
Auth Tokens

Auth tokens authenticate end-users (not server-side calls). The flow:
  1. Your backend creates a user via REST API (using fullAccess key)
  2. Your backend creates an auth token for that user via POST /users/{uid}/auth_tokens
  3. Your client app uses the auth token to log in via the CometChat SDK
Auth tokens are tied to a specific user and can be scoped to a platform and device. See Auth Tokens API for full details.

​
Acting on Behalf of Users

Some endpoints support the onBehalfOf header, which lets a server-side call act as a specific user: 
curl -X POST "https://<appId>.api-<region>.cometchat.io/v3/messages" \
  -H "apikey: YOUR_REST_API_KEY" \
  -H "onBehalfOf: cometchat-uid-1" \
  -H "Content-Type: application/json" \
  -d '{"receiver": "cometchat-uid-2", "receiverType": "user", "type": "text", "data": {"text": "Hello"}}'
Whether onBehalfOf is required, optional, or not supported varies per endpoint — check each endpoint’s documentation.

​
Security Best Practices

  • Store API keys in environment variables or a secrets manager, never in source code
  • Use fullAccess keys only on your backend server
  • Rotate API keys periodically via the API Keys API
  • Generate auth tokens server-side and pass them to clients
  • Use HTTPS for all API calls (enforced by CometChat)