> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/authorization-integration/vendor-integration-guide.md).

# Vendor Integration Guide (End-to-End)

This page is for software vendors who want to embed MaiAgent Web Chat into their product and integrate it with their own account system for authorization. After a user logs into your system, the AI assistant recognizes who they are, can recall their conversation history, and can call your system's API with **their permissions**.

The integration journey consists of five stages. This page explains what each stage does and in what order, with links to the corresponding technical documentation for details.

## Integration Overview <a href="#overview" id="overview"></a>

```mermaid
flowchart LR
    subgraph ONCE["One-Time Setup"]
        A["Embed Web Chat"] --> B["Batch backfill existing users"]
    end
    subgraph DAILY["Day-to-Day Operations (Account Lifecycle)"]
        C["Create contact when adding users"] --> D["Update Token on login"]
        D --> E["Re-sync on Token refresh"]
        E --> F["Revoke credentials on logout"]
    end
    ONCE --> DAILY
```

The core concept is just one thing: **Contact** — each user in your system maps to a Contact in MaiAgent. A Contact carries conversation history, personalization attributes, knowledge base query scope, and tool credentials. Every action in the authorization integration is essentially maintaining the "your user <-> Contact" mapping and its credentials. For a conceptual introduction, see [Contact Introduction and Integration](/tech/en/authorization-integration/contacts.md).

### What the Frontend and Backend Are Each Responsible For <a href="#frontend-backend-split" id="frontend-backend-split"></a>

Throughout this journey, your frontend is only responsible for "loading the chat window." All calls that involve Tokens or API Keys are initiated by your backend:

```mermaid
flowchart LR
    subgraph FE["Your Frontend"]
        A["Embed code loads SDK<br/>config includes contactId"]
        B["Call signOut on logout"]
    end
    subgraph BE["Your Backend"]
        C["Login / Refresh: POST setup-contact-credentials"]
        D["Batch backfill: POST bulk-import"]
        E["Profile sync: PATCH contacts"]
        F["Logout: DELETE tool credentials"]
    end
    subgraph MA["MaiAgent"]
        G["Chat Window<br/>chat.maiagent.ai"]
        H["API<br/>api.maiagent.ai"]
    end
    A --> G
    B --> G
    C --> H
    D --> H
    E --> H
    F --> H
```

Among these, `setup-contact-credentials` does not require an API Key (public endpoint); `bulk-import`, `PATCH`, and `DELETE` all require `Authorization: Api-Key` authentication and can only be called from the backend.

## Step 1: Embed Web Chat <a href="#step-embed" id="step-embed"></a>

Choose an embedding approach based on your product's form factor. Both use the same SDK and the same Contact mechanism:

| Form                                      | Best for                                                   | Documentation                                                                      |
| ----------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Chat bubble (floating/sidebar)            | Customer service, inquiries, and other auxiliary features  | [Web Chat Embed & SDK](/tech/en/api-integration/web-chat-sdk.md)                   |
| MaiGPT mode (full ChatGPT-like interface) | Main functional area of the page, site-wide AI entry point | [MaiGPT Mode Embed](/tech/en/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) |

{% hint style="info" %}
For Web Chat instances that will use identity integration, it is recommended to configure the "Allowed Embed Origins" list at this point (currently set by the MaiAgent team on your behalf — provide the domain list to your integration contact). This restricts the origins that can call the Identity Sync API. See [Allowed Embed Origins](/tech/en/api-integration/web-chat-sdk.md#embed-origin-allowlist).
{% endhint %}

## Step 2: Initial Integration — Batch Backfill Existing Users <a href="#step-backfill" id="step-backfill"></a>

When integrating an existing system for the first time, start by backfilling contacts for all current users. There are two approaches:

| Approach                                               | Best for                                                                                                        | Documentation                                                                                                |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Excel batch import** (`POST /contacts/bulk-import/`) | Large user bases (up to 10,000 rows per batch), supports query metadata and API tool credentials simultaneously | [Contact Batch Import](/tech/en/authorization-integration/contacts.md#bulk-import)                           |
| **Per-record identity sync API calls**                 | Gradual backfill through the login flow, or small volumes                                                       | [Batch Backfill for Existing Users](/tech/en/authorization-integration/contact-credentials-sync.md#backfill) |

It is fine if you do not have the user's Access Token at the time of backfill — just create the mapping first. Token credentials will be added by the login flow in Step 4 when each user next logs in.

## Step 3: Create a Contact When Adding Users <a href="#step-create-user" id="step-create-user"></a>

After the backfill is complete, add a single API call to your "create account" flow so that new users get a corresponding Contact right away:

* Have the backend call the [Identity Sync API (`setup-contact-credentials`)](/tech/en/authorization-integration/contact-credentials-sync.md), using your system's user identifier as the `sourceId`
* Store the returned `contactId` in your member data table (see the [Login Flow Integration Point](/tech/en/authorization-integration/contact-credentials-sync.md#login-flow) for a suggested field design)

`sourceId` is an idempotent key: repeated calls with the same `sourceId` only update the existing record and never create duplicates, so this step can safely coexist with Steps 2 and 4.

## Step 4: Login and Token Refresh <a href="#step-login-refresh" id="step-login-refresh"></a>

Each time a login succeeds and an Access Token is generated, have the backend call the same identity sync API again, passing in the **new Token** (`mcpCredentials`). This allows the AI assistant to call your system's API with that user's identity and permissions. On Token refresh, use the same approach — just call the API again. The same (contact, tool) combination results in an update, not a duplicate. For the full sequence diagram and considerations (asynchronous calls, not blocking login on failure), see [Contact Identity Sync and Token Update](/tech/en/authorization-integration/contact-credentials-sync.md).

On the frontend, pass the `contactId` when initializing Web Chat on the page. See [Identify Users](/tech/en/api-integration/web-chat-sdk.md#identify-users).

{% hint style="info" %}
If you do not need the AI to call your system's API and only need to recognize users, you can skip the backend entirely: just include `auth` in the frontend config. For a comparison of the trade-offs, see [Choosing Between Frontend Auth and Backend Integration](/tech/en/authorization-integration/contact-credentials-sync.md#frontend-vs-backend).
{% endhint %}

## Step 5: Logout and Credential Revocation <a href="#step-logout" id="step-logout"></a>

There are two things to do at logout, each with a different scope — it is recommended to do both:

* **Frontend**: Call the SDK's `signOut()` to return the chat window to anonymous state
* **Backend**: Delete the contact's tool credentials so the AI can no longer call tools as that user

For the detailed API and a comparison of the two, see [Logout and Credential Revocation](/tech/en/authorization-integration/contact-credentials-sync.md#logout-revoke).

## Integration Checklist <a href="#checklist" id="checklist"></a>

| Stage      | Action                                                                 | Documentation                                                                                                                                                     |
| ---------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Setup      | Embed Web Chat (standard or MaiGPT mode)                               | [Web Chat Embed & SDK](/tech/en/api-integration/web-chat-sdk.md) / [MaiGPT Mode](/tech/en/api-integration/web-chat-sdk/web-chat-maigpt-mode.md)                   |
| Setup      | Provide domain list to MaiAgent to configure "Allowed Embed Origins"   | [Allowed Embed Origins](/tech/en/api-integration/web-chat-sdk.md#embed-origin-allowlist)                                                                          |
| Setup      | Add `maiagent_contact_id` field to the member data table               | [Login Flow Integration Point](/tech/en/authorization-integration/contact-credentials-sync.md#login-flow)                                                         |
| Setup      | Batch backfill existing users                                          | [Contact Batch Import](/tech/en/authorization-integration/contacts.md#bulk-import)                                                                                |
| Operations | Call the identity sync API in the account creation flow                | [Contact Identity Sync and Token Update](/tech/en/authorization-integration/contact-credentials-sync.md)                                                          |
| Operations | Update credentials in the login/Token refresh flow                     | [When to Call](/tech/en/authorization-integration/contact-credentials-sync.md#when-to-call)                                                                       |
| Operations | Revoke credentials in the logout flow                                  | [Logout and Credential Revocation](/tech/en/authorization-integration/contact-credentials-sync.md#logout-revoke)                                                  |
| Advanced   | Sync department, membership tier, and other personalization attributes | [Sync Contact Profile](/tech/en/authorization-integration/contact-credentials-sync.md#sync-contact-profile)                                                       |
| Advanced   | Restrict each user's knowledge base retrieval scope via query metadata | [Knowledge Management Permissions (Query Metadata)](/tech/en/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/en/authorization-integration/vendor-integration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.