# Create a sub-user

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

Canonical: https://www.chat-data.com/api-reference/create-sub-user

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

Create a new sub-user for your company. Sub-users can log in to a branded portal on your custom domain and access their assigned chatbots.

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.

Your workspace's SSO company must exist and have a login domain before you can create sub-users. The sub-user's email must be unique within the company. Creating a sub-user sends no email.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| email | string | yes | The sub-user's email address, stored in lowercase. It must be unique within the company, and for a sub-user without a password (who signs in by magic link) the mailbox must accept mail. |
| name | string | no | The sub-user's display name. HTML tags are stripped. |
| password | string | no | Optional password for email/password login. It must satisfy at least three of the following - at least 8 characters, an uppercase letter, a lowercase letter, a number, a special character. Without a password the sub-user signs in by magic link (or Google, when enabled). |
| chatbotIds | array of string | yes | Array of chatbot IDs to assign to this sub-user. All IDs must belong to chatbots in your workspace. Duplicates are automatically removed. |
| permissions | array of string | no | Permissions granted to the sub-user. Defaults to the company's default permission if not provided. Invalid values are silently removed; if none of the provided values is valid, the request fails. |
| analyticsDashboardSections | array of string | no | Analytics dashboard sections visible to the sub-user. Defaults to the company's configured sections if not provided. Unknown section names are ignored. |
| googleEnabled | boolean | no | Whether to enable Google sign-in for this sub-user. It is enabled automatically if the company has Google sign-in configured. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/sub-users' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "jane@chat-data.com",
  "chatbotIds": [
    "6650f1c2a9e4b83d2c7a1f05",
    "6650f1c2a9e4b83d2c7a1f06"
  ]
}'
```

## Example response (201)

```json
{
  "_id": "6650f1c2a9e4b83d2c7a1f9a",
  "company": "6650f1c2a9e4b83d2c7a1f3c",
  "email": "jane@chat-data.com",
  "name": "Jane Doe",
  "avatar": "",
  "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"
}
```

## Responses

| Status | Description |
| --- | --- |
| 201 | Sub-user created successfully. |
| 400 | The sub-user could not be created. For example: `email` is missing, invalid or (for a sub-user without a password) not deliverable, `chatbotIds` is empty or contains an ID that is not a chatbot in your workspace, the workspace has no SSO company or the company has no login domain, `name` is not a string or is longer than 100 characters, none of the given `permissions` is valid, the password is too weak, or a sub-user with this email already exists. |
| 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. |