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

# Software Vendor Integration Guide (End-to-End)

An end-to-end guide for software vendors to embed Web Chat in their products and integrate permissions: embedding, batch backfill, login synchronization, token refresh, and logout revocation

This page is intended for software vendors that want to embed MaiAgent Web Chat in their products and integrate it with their account systems for permission management. After users log in to your system, the AI assistant can identify them, retrieve their conversation history, and call your system's APIs with **their permissions**.

The integration journey consists of five stages. This page explains what to do at each stage 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["Daily Operations (Account Lifecycle)"]
        C["Create Contact When Adding a User"] --> D["Update Token at Login"]
        D --> E["Synchronize Again When Token Is Refreshed"]
        E --> F["Revoke Credentials at Logout"]
    end
    ONCE --> DAILY
```

There is only one core concept: **Contact**. Each user in your system corresponds to a contact in MaiAgent. Conversation history, personalized attributes, knowledge base query scope, and tool credentials are associated with the contact. Every permission integration action essentially maintains the mapping between "your user ↔ contact" and the associated credentials. See [Introduction to and Integration with Contacts](/tech/en/authorization-integration/contacts.md) for an overview.

### Frontend and Backend Responsibilities <a href="#frontend-backend-split" id="frontend-backend-split"></a>

Throughout the journey, your frontend is responsible only for loading the chat window. All calls involving 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 at Logout"]
    end
    subgraph BE["Your Backend"]
        C["Login/Refresh: POST setup-contact-credentials"]
        D["Batch Backfill: POST bulk-import"]
        E["Data Synchronization: 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
```

`setup-contact-credentials` does not require an API key because it is a public endpoint. `bulk-import`, `PATCH`, and `DELETE` all require `Authorization: Api-Key` authentication and must be called from the backend.

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

Choose an embedding method based on your product. Both methods use the same SDK and contact mechanism:

| Format                                    | Best for                                                      | Documentation                                                                      |
| ----------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Chat bubble (floating/sidebar)            | Supporting features such as customer service and consultation | [Web Chat Embedding and SDK](/tech/en/api-integration/web-chat-sdk.md)             |
| MaiGPT mode (full ChatGPT-like interface) | Primary page features and site-wide AI entry points           | [Embed MaiGPT Mode](/tech/en/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) |

{% hint style="info" %}
For Web Chat with identity integration, we recommend configuring the "Allowed Embed Domains" list at this stage. The MaiAgent team currently configures this for you; provide the domain list to your integration contact. This limits the origins that can call the identity synchronization API. See [Allowed Embed Domains](/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, begin by creating contacts for all existing users. There are two approaches:

| Method                                                  | Best for                                                                                                              | Documentation                                                                                            |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Excel batch import** (`POST /contacts/bulk-import/`)  | Large numbers of users (up to 10,000 rows per request), with optional knowledge query scopes and API tool credentials | [Batch Import Contacts](/tech/en/authorization-integration/contacts.md#bulk-import)                      |
| **Call the identity synchronization API for each user** | Gradually backfilling users through the login flow or handling a small number of users                                | [Batch Backfill Existing Users](/tech/en/authorization-integration/contact-credentials-sync.md#backfill) |

It is fine if the user's access token is unavailable during backfill—create the mapping first. The login flow in Step 4 adds the token credentials the next time each user logs in.

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

After backfill is complete, add an API call to your system's account creation flow so that every new user has a corresponding contact from the outset:

* From the backend, call the [identity synchronization 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 database. See [Where to Integrate with the Login Flow](/tech/en/authorization-integration/contact-credentials-sync.md#login-flow) for a recommended field design.

`sourceId` is an idempotency key: repeated calls with the same `sourceId` update the existing contact instead of creating duplicates. This step can therefore safely coexist with Steps 2 and 4.

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

After each successful login generates an access token, have the backend call the same identity synchronization API again with the **new token** (`mcpCredentials`). This allows the AI assistant to call your system's APIs using that user's identity and permissions. Use the same approach when refreshing the token—simply call the API again. The same contact/tool pair is updated rather than duplicated. See [Contact Identity Synchronization and Token Updates](/tech/en/authorization-integration/contact-credentials-sync.md) for the complete sequence diagram and considerations such as making the call asynchronously and not blocking login on failure.

On the frontend, include `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 the AI does not need to call your system's APIs and only needs to identify the user, you can omit the backend integration entirely and include `auth` in the frontend config. See [Choosing Between Frontend auth and Backend Integration](/tech/en/authorization-integration/contact-credentials-sync.md#frontend-vs-backend) for the trade-offs.
{% endhint %}

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

Perform both of the following at logout because they have different scopes:

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

See [Logout and Credential Revocation](/tech/en/authorization-integration/contact-credentials-sync.md#logout-revoke) for detailed APIs and a comparison of the two actions.

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

| Stage      | Action                                                                     | Documentation                                                                                                                                                     |
| ---------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Setup      | Embed Web Chat (standard or MaiGPT mode)                                   | [Web Chat Embedding and 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 the domain list so MaiAgent can configure "Allowed Embed Domains"  | [Allowed Embed Domains](/tech/en/api-integration/web-chat-sdk.md#embed-origin-allowlist)                                                                          |
| Setup      | Add a `maiagent_contact_id` field to the member database                   | [Where to Integrate with the Login Flow](/tech/en/authorization-integration/contact-credentials-sync.md#login-flow)                                               |
| Setup      | Batch backfill existing users                                              | [Batch Import Contacts](/tech/en/authorization-integration/contacts.md#bulk-import)                                                                               |
| Operations | Call the identity synchronization API during account creation              | [Contact Identity Synchronization and Token Updates](/tech/en/authorization-integration/contact-credentials-sync.md)                                              |
| Operations | Update credentials during login/token refresh                              | [When to Call](/tech/en/authorization-integration/contact-credentials-sync.md#when-to-call)                                                                       |
| Operations | Revoke credentials during logout                                           | [Logout and Credential Revocation](/tech/en/authorization-integration/contact-credentials-sync.md#logout-revoke)                                                  |
| Advanced   | Synchronize personalized attributes such as department and membership tier | [Synchronize Contact Data](/tech/en/authorization-integration/contact-credentials-sync.md#sync-contact-profile)                                                   |
| Advanced   | Use Query Metadata to restrict each user's knowledge base retrieval scope  | [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.