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

> How to authenticate REST API requests to CometChat.

All CometChat REST API requests must be authenticated using an API key passed in the `apikey` HTTP header.

<Note>
  **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.
</Note>

<Note>
  **Management APIs** use a different authentication mechanism — `key` and `secret` headers, not the `apikey` header. See the [Management APIs overview](/rest-api/management-apis) for details.

  ```bash theme={null}
  curl -X GET "https://apimgmt.cometchat.io/apps" \
    -H "key: YOUR_MANAGEMENT_KEY" \
    -H "secret: YOUR_MANAGEMENT_SECRET"
  ```
</Note>

## API Key Scopes

CometChat supports two API key scopes:

| Scope        | Dashboard Name | Permissions                                                                                                        |
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `fullAccess` | REST API Key   | All REST API operations: create/update/delete users, groups, messages, manage settings, etc. Use server-side only. |
| `authOnly`   | Auth Key       | Can only create users and generate auth tokens. Intended for quick demos and prototyping.                          |

<Warning>
  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.
</Warning>

## Making Authenticated Requests

Include the API key in the `apikey` header (all lowercase):

```bash theme={null}
curl -X GET "https://<appId>.api-<region>.cometchat.io/v3/users" \
  -H "apikey: YOUR_REST_API_KEY"
```

<Note>
  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.
</Note>

## 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](/rest-api/auth-tokens) 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:

```bash theme={null}
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](/rest-api/api-keys)
* Generate auth tokens server-side and pass them to clients
* Use HTTPS for all API calls (enforced by CometChat)