Sub-User Management

Create a sub-user

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) 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.

post/sub-users

Request

  • Base URL: https://api.chat-data.com/api/v2
  • URL: https://api.chat-data.com/api/v2/sub-users
  • Auth: HTTP bearer

Request body

emailstring email required

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.

namestring

The sub-user's display name. HTML tags are stripped.

passwordstring

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).

chatbotIdsstring[] required

Array of chatbot IDs to assign to this sub-user. All IDs must belong to chatbots in your workspace. Duplicates are automatically removed.

permissionsstring[]

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.

analyticsDashboardSectionsstring[]

Analytics dashboard sections visible to the sub-user. Defaults to the company's configured sections if not provided. Unknown section names are ignored.

googleEnabledboolean

Whether to enable Google sign-in for this sub-user. It is enabled automatically if the company has Google sign-in configured.

Example request

{
  "email": "jane@chat-data.com",
  "name": "Jane Doe",
  "password": "Maple-Harbor-42",
  "chatbotIds": [
    "6650f1c2a9e4b83d2c7a1f05",
    "6650f1c2a9e4b83d2c7a1f06"
  ],
  "permissions": [
    "read",
    "train"
  ],
  "analyticsDashboardSections": [
    "Overview",
    "Messages Timeline",
    "Chats"
  ]
}

Response

Sub-user created successfully.

_idstring required

The unique identifier of the sub-user.

companystring required

The ID of the company this sub-user belongs to.

emailstring email required

The sub-user's email address.

namestring

The sub-user's display name.

avatarstring

URL of the sub-user's avatar image, or an empty string if none is set.

permissionsstring[] required

Permissions granted to this sub-user.

analyticsDashboardSectionsstring[]

Analytics dashboard sections visible to this sub-user.

hasPasswordboolean required

Whether the sub-user has a password configured (the actual password is never returned).

hasGoogleboolean required

Whether the sub-user has signed in with a linked Google account (the Google ID is never returned). It stays false when Google sign-in is only enabled.

createdAtstring date-time

Timestamp when the sub-user was created.

lastLoginAtstring date-time

Timestamp of the sub-user's last sign-in. Absent until they first sign in.

Example response

{
  "_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,
  "createdAt": "2026-10-14T09:30:00.000Z",
  "lastLoginAt": "2026-10-14T10:15:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.