# List sub-users

`GET https://api.chat-data.com/api/v2/sub-users`

Canonical: https://www.chat-data.com/api-reference/list-sub-users

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Returns a list of all sub-users of your workspace's company. Each sub-user includes its assigned chatbots' names, not just their IDs. The response is an empty array when the workspace has no SSO company.

Requires the SSO Login add-on (see [plans](/pricing)) and a workspace API key; without the add-on, or with a chatbot-scoped key, the request gets a 403.

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/sub-users' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY"
```

## Example response (200)

```json
[
  {
    "_id": "6650f1c2a9e4b83d2c7a1f9a",
    "company": "6650f1c2a9e4b83d2c7a1f3c",
    "email": "jane@chat-data.com",
    "name": "Jane Doe",
    "avatar": "https://example.blob.core.windows.net/chatfiles/6650f1c2a9e4b83d2c7a1f9a/avatar.png",
    "chatbotIds": [
      {
        "_id": "6650f1c2a9e4b83d2c7a1f05",
        "name": "Support Bot"
      },
      {
        "_id": "6650f1c2a9e4b83d2c7a1f06",
        "name": "Sales Assistant"
      }
    ],
    "permissions": [
      "read",
      "train"
    ],
    "analyticsDashboardSections": [
      "Overview",
      "Messages Timeline",
      "Chats"
    ],
    "hasPassword": true,
    "hasGoogle": false,
    "createdAt": "2026-10-14T09:30:00.000Z",
    "lastLoginAt": "2026-10-14T10:15:00.000Z"
  }
]
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The request used a chatbot-scoped API key (`This operation requires a user-level API key, not a chatbot-specific key`, with `status: error`), or the workspace does not have the SSO Login add-on (`SSO Login is unavailable with your current plan`, with no `status` field). |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |
| 500 | An unexpected error occurred while processing the request; `message` contains the error. |