Add MaiGPT to Your System

An end-to-end guide to adding MaiGPT to your own system for organization members: provision members, issue tokens, embed the frontend, handle sign-out, and complete acceptance testing—all on one page

This page is designed to be read from start to finish by engineers who need to add MaiGPT to their system. Whether you operate an enterprise portal, an internal workspace, or a SaaS platform managed for customers, the process is the same as long as users are members of a MaiAgent organization (such as employees or staff). Each step tells you exactly what to do, with links for deeper details when needed.

If your users are your customers, members, or anonymous visitors, rather than organization members, they cannot use the MaiGPT product itself. Use the custom AI Agent + MaiGPT window mode instead. For contact identity integration, see the Software Vendor Integration Guide.

Overview

When complete, employees sign in to your system and MaiGPT appears directly on the page. They can generate images, use Deep Research, and access connectors. Their permissions, credits, and conversation history all follow their MaiAgent member identity. They do not need to sign in to MaiAgent separately or even know that MaiAgent is involved.

Prerequisites

Item	Where to get it
A MaiAgent organization with a plan that includes MaiGPT and identity synchronization	Contact sales if you are unsure
An organization API Key owned by the organization owner or someone with the “Organization Overview” administration permission	See Quickstart for instructions
The MaiGPT Web Chat ID	In the response from GET /api/v1/web-chats/, find the entry whose name is MaiGPT and whose accessType is web
Roles created and permissions configured in advance	In the backend, go to “Organization Settings → Organization Overview → Edit Role Permissions.” Create a role such as “Employee” and enable permission to use MaiGPT (configuration instructions). All member capabilities come from their role. If you skip this step, none of the later steps will work
Decide where members will come from	Choose one of the three options in the next section

Step 1: Provision Members

Your users must first be members of the MaiAgent organization. Choose the easiest of these three approaches:

Are people in your organization already using MaiAgent? Connecting SCIM will not invalidate their existing accounts or create duplicate accounts. Existing members brought under management will subsequently be synchronized with your system. For details, see What Happens to Existing Accounts and Members.

Your system manages users (recommended)

When users are created, updated, or deactivated in your system, call the MaiAgent SCIM endpoint as part of the same event to keep members synchronized in real time.

1. In the backend, go to “Organization Settings → Identity Synchronization,” select SCIM, and copy the Endpoint URL and Token from the “Connection Information” tab. The Token is shown only once; store it in a server environment variable.

2. Add the MaiAgentMembers client from the real-time synchronization page to your project and call it from the event:

members = MaiAgentMembers()   # Reads MAIAGENT_SCIM_URL / MAIAGENT_SCIM_TOKEN from environment variables

# Create user
user.maiagent_member_id = members.on_user_created(
    external_id=user.id, email=user.email, name=user.display_name, groups=["Employee"],
)
# Rename or transfer department
members.on_user_updated(user.maiagent_member_id, user.id, user.email, user.display_name, ["Employee"])
# Suspend access or offboard
members.on_user_deactivated(user.maiagent_member_id)

1. Before the initial launch, run on_user_created once for all existing users (it is idempotent; see batch backfill). After that, use events to keep them synchronized.

You only have a roster (HR export, Excel, or database)

Use the roster synchronization tool. Prepare a four-column CSV or JSON file containing employee ID, Email, name, and role; configure the SCIM connection environment variables; run with --dry-run to review the plan before executing it; then schedule it to run once a day. Users present on the roster are created or updated, while users no longer on the roster are deactivated.

You use Okta, Entra ID, or JumpCloud

Enter the SCIM Endpoint URL and Token in your IdP's provisioning settings. The IdP will automatically push users and groups. For details, see Push from an IdP.

Remember these three points. They are the most common sources of integration issues:

• Role names must match roles created in the backend: The name supplied in groups when SCIM creates a member must match the role whose permissions were configured in the backend. If the name does not match, a new role without permissions is created automatically.

• Email is the account key: userName is the Email later used to issue a token. Email cannot be changed through SCIM after the account is created.

• Accounts created through SCIM do not have passwords: Employees following this path will not sign in to MaiAgent, which is intentional. If you also want to provide access to the MaiGPT web version or app, configure SSO separately.

Step 2: Issue a Member Token in the Backend

Create an endpoint in your backend that can be called only by signed-in users (for example, GET /maigpt-token). Internally, use the organization API Key to request a short-lived token for that member from MaiAgent:

curl -X POST https://api.maiagent.ai/api/v1/members/embed-tokens/ \
  -H "Authorization: Api-Key <your organization API Key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

A successful request returns 201:

{
  "accessToken": "<short-lived member JWT>",
  "organizationId": "8d2f...-...",
  "expiresAt": 1789906401000,
  "member": { "id": "c1a4...", "userId": "5e77...", "email": "[e-mail]", "name": "Alice" }
}

Return the entire response to the frontend unchanged. Rules and status codes:

Fact	Description
Valid for 15 minutes; no refresh token is issued	The frontend SDK handles renewal automatically (Step 3). Your backend only needs to “issue one whenever called”—always issue a new token; do not cache it
The token can be used only with MaiGPT conversation endpoints	Using it with any /api/v1/ API always returns 401; even if leaked, it cannot access organization data
401 / 403	No Api-Key was used, or the Key owner is not an owner or organization administrator
404	The Email does not belong to an active member of this organization—the first step was not completed, or the member has been deactivated
Every issuance is recorded in the audit log	It can be reviewed in the organization's API request logs; the token in the response is not logged

For parameters and more details, see Issue a Member Token.

Step 3: Embed in the Frontend

Add the embed code to the page where MaiGPT should appear, and point auth.getToken to the endpoint created in Step 2. The SDK handles everything else: it retrieves a token during initialization, automatically retrieves another before expiry, and continues using the same conversation.

<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<MaiGPT Web Chat ID>',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    maigptTitle: 'Acme GPT',            // Optional: brand name in the upper-left corner
    locale: 'zh-TW',                    // Optional: interface locale
    auth: {
      getToken: async () => {
        const res = await fetch('/maigpt-token', { credentials: 'include' })
        const { accessToken, organizationId, member } = await res.json()
        return { accessToken, organizationId, sourceId: member.userId }
      },
    },
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

sourceId must be set to member.userId from the response—not member.id or the user ID from your own system. MaiGPT uses it to associate conversations with the member. If it is incorrect, conversations become anonymous and the member's history will not be visible.

Set the container height yourself. In an SPA, wait until the container is mounted before loading the SDK. baseUrl and the SDK URL point to the SaaS service; for a private deployment, replace them with your domain. For layout and other parameters, see Embed in MaiGPT Mode.

Step 4: Sign-Out and Offboarding

Event	What you need to do	Result
A user signs out of your system	Call MaiAgent.auth.signOut() in the frontend	The iframe clears the identity and stops renewal; an issued token may remain valid for up to 15 minutes
A user leaves or access is suspended	Deactivate the user using the Step 1 method (on_user_deactivated, removal from the roster, or deactivation in the IdP)	Subsequent issuance returns 404, and the embedded page naturally stops working; conversation and credit records are retained
A user returns	Reactivate the user using the Step 1 method	The role and history are restored

Step 5: Acceptance Testing

Verify each item in order. Every item has a clear pass condition:

1. The member exists and has a role: In “Member Management” in the backend, confirm that the person appears and has the role whose permissions you configured.

2. Issuance succeeds: The curl command from Step 2 returns 201; using an Email that does not exist returns 404.

3. Conversation works: Open MaiGPT on the embedded page and send a message; verify that it receives a response. Sign in to the MaiGPT web version as that member (if SSO is configured), or check the backend conversation records to confirm the conversation appears.

4. Capabilities are correct: Ask it to generate an image. If the role has access to connectors and Deep Research, those options appear.

5. Renewal is seamless: Leave the page open for more than 15 minutes, then send another message. The same conversation continues without reloading the page.

6. Sign-out takes effect: After signOut(), attempts to send another message are rejected. After deactivating the member, Step 2 returns 404.

After Launch

• Rotate the SCIM Token and API Key: The backend displays a reminder after a SCIM Token is more than 180 days old. When a new one is generated, the old one is immediately invalidated, so remember to update the server environment variable at the same time.

• Plan capacity: The number of members affects built-in Agent seats and per-member Credits. See Manage Member Credit Quotas.

• Auditing: Every token issuance appears in the organization's API request logs. Every SCIM synchronization appears under “Identity Synchronization → Synchronization Records” in the backend.

Troubleshooting

Symptom	Cause	Resolution
Issuance returns 404	The Email does not belong to an active member of this organization	Return to Step 1 and confirm that the member exists, is active, and has the same Email (case-insensitive)
Issuance returns 403	The API Key owner is neither an owner nor an organization administrator	Use a Key issued by an administrator
The chat window says “Failed to create conversation (400): You do not have permission to use MaiGPT”	The member's role does not have permission to use MaiGPT, or auth was not provided	Enable MaiGPT in the backend role permissions; confirm that getToken returns accessToken and organizationId
The conversation is anonymous and history is unavailable	sourceId is incorrect	Use member.userId
Sending a message fails after 15 minutes	getToken was not called or failed (check the browser console for [MaiAgent] errors)	Confirm that the endpoint is available to signed-in users and that its response format is correct
The member was created but cannot use anything	The member has no role, or the role has no permissions	Configure role permissions in the backend; assign the same role name through SCIM
An Email change did not take effect	SCIM does not allow Email changes	Change it in the backend, or deactivate the old account and create one with the new Email

For more SCIM error codes, see the roster synchronization tool error reference.

Further Reading

• Member Provisioning: SCIM / Invitation / SSO — Complete SCIM API reference and comparison of the three approaches

• Real-Time Synchronization: Call from User Events / Roster Synchronization Tool

• Integrate MaiGPT: Choose the Right Assistant and Enable Capabilities — MaiGPT product vs. custom assistants and complete parameters for embedding member identity

• Web Chat Embedding and SDK / Embed in MaiGPT Mode