> For the complete documentation index, see [llms.txt](https://documents.cxgenie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documents.cxgenie.ai/marketplace/custom-authentication-1.md).

# Custom Authentication

This guide helps you connect CX Genie with your system to automatically retrieve user contact information through a secure API, instead of manual input.

#### 🛠️ Step 1: Set up Authentication API <a href="#step-1-set-up-authentication-api" id="step-1-set-up-authentication-api"></a>

1. **Go to** `Custom Authentication` **in CX Genie** (under Development in Bot Detail).
2. **Enable the toggle** to activate the feature.
3. **Enter your Authentication URL**\
   \- This should be an API endpoint in your system that CX Genie can call via a `POST` request.
4. **Example request body CX Genie will send:**

`{ "access_token": "...", "user_id": "..." }`

#### 🪪 Step 2: Pass Access Token and Optional User Info in Embed Script <a href="#step-2-pass-access-token-and-optional-user-info-in-embed-script" id="step-2-pass-access-token-and-optional-user-info-in-embed-script"></a>

To use Custom Authentication, you must pass an `access_token` from your website into the CX Genie chat widget.

Use the `data-token` attribute in your script tag:

`<script src="https://your-widget-url.js" data-token="your_access_token"> </script>`

**✅ Optionally, pass additional user fields:**

If enabled in the **Additional request body** section (e.g., "User ID" is checked), you can also pass more user-specific data via additional `data-` attributes:

| Attribute           | Description           |
| ------------------- | --------------------- |
| `data-user-id`      | Unique ID of the user |
| `data-email`        | User’s email address  |
| `data-name`         | Full name             |
| `data-phone-number` | Phone number          |

**Example:**

`<script src="https://your-widget-url.js" data-token="your_access_token" data-user-id="12345" data-email="user@example.com" data-name="John Doe" data-phone="0987654321"> </script>`

These values will be included in the request body sent to your authentication API if configured accordingly.

#### 📤 Step 3: Configure the Response Format <a href="#step-3-configure-the-response-format" id="step-3-configure-the-response-format"></a>

CX Genie needs to determine whether a user already exists in the system. You must configure your API to return a response with one of the following primary identifiers:

* `id` (default)
* `email`
* `phone_number`

You can select the identification method from the **"Identify method"** dropdown in the **Custom Authentication** screen.

**➤ Required Field Based on Your Selection:**

| Selected Method | Required in `data` response |
| --------------- | --------------------------- |
| `Id`            | `id`                        |
| `Email`         | `email`                     |
| `Phone number`  | `phone_number`              |

**✅ Full Example Response:**

`{ "data": { "id": "12345", "email": "user@example.com", "name": "John Doe", "phone_number": "0987654321", "metadata": {} } }`

> 🔍 **Note:** The field you choose must always be included in the response. If it's missing, the authentication may fail.

#### 🧪 Step 4: Test Your Setup <a href="#step-4-test-your-setup" id="step-4-test-your-setup"></a>

Use the **Testing panel** on the right side of the screen:

1. Enter a sample `access_token` and select additional body fields.
2. Click **Send test request** to verify your API is responding correctly.

***

#### 📝 Tips <a href="#tips" id="tips"></a>

* You can use the `metadata` field to give the bot more context about the user.
* Ensure your API is secured and only accessible from authorized sources.

<br>