Contact Identity Sync and Token Update

Enterprise systems sync contact identity and update Token credentials via setup-contact-credentials when creating users and on each login

After embedding Web Chat (including MaiGPT mode) into their product, enterprise systems need to let the AI know "who is asking": so the AI can trace back the user's conversation history and access the enterprise system's API with that user's permissions when calling MCP tools.

The setup-contact-credentials API accomplishes two things in a single call:

1. Create or update the mapping between "enterprise system account ↔ MaiAgent Contact"

2. Write the user's Access Token to Contact MCP Credentials, enabling the AI assistant to call tools on the user's behalf

For the concept of Contact and the overall integration flow, refer to Contact Introduction and Integration first. If you do not use MCP tools and only need to create contact mappings, you can also use the POST /api/v1/contacts/ flow on that page; the API on this page is suited for scenarios where "Token sync is needed at login time."

Choosing Between Frontend Auth and Backend Integration

This API also has a frontend version: the embed SDK's auth configuration (see Web Chat Embedding and SDK) internally has the chat widget automatically call the same API. Both paths create the same set of contacts (the same sourceId maps to the same person); the only difference is who makes the call:

	Frontend auth (SDK automatic)	Backend integration (this page)
Caller	User's browser	Your backend server
Integration cost	Low: add an auth object to the config	Medium: add one API call to the login flow + store contactId
Token confidentiality	mcpCredentials appears on the frontend page; users can see their own token in the source code	Token never passes through the frontend
Best for	Only need to identify users and preserve cross-device conversations	Need to bind MCP credentials so the AI can call APIs with user permissions

1. When to Call

Scenario	Approach
Creating a new user	Call this API during the account creation flow and store the returned contactId in the member data table
Each login	After login succeeds and an Access Token is generated, call this API before returning the result to the frontend, passing in the new Token (the same sourceId will auto-update; no duplicates are created)
Backfilling existing systems	Call this API for each existing user to backfill contact mappings; see Batch Backfill for Existing Users
Token expiry / refresh	Simply call this API again with the new Token
Logout	Call the SDK's signOut() on the frontend to return to anonymous; on the backend, delete the contact's tool credentials — see Logout and Credential Revocation

2. API Specification

Item	Value
Method	POST
URL	https://api.maiagent.ai/api/v1/web-chats/{webChatId}/setup-contact-credentials/
Authentication	No API Key required (public endpoint; only the WebChat ID is needed)
Content-Type	application/json
Rate limit	30 requests per IP per minute

The URL uses the SaaS environment (api.maiagent.ai) as an example; for private cloud / on-premises deployments, replace it with the API domain of your environment.

Request Body

{
  "sourceId": "user-12345",
  "name": "王小明",
  "mcpCredentials": {
    "toolId": "your-mcp-tool-id",
    "headers": {
      "Authorization": "Bearer <<User's Access Token>>"
    }
  }
}

Field	Required	Description
sourceId	✅	The unique identifier of the user in the enterprise system. Repeated calls with the same sourceId will update rather than create duplicates. Use non-guessable values (e.g., UUID); see the security note below
name		User display name, shown in the contact list in the MaiAgent dashboard; defaults to Anonymous if not provided. Only takes effect when the contact is first created; to update the name later, use Sync Contact Profile
mcpCredentials.toolId		The MCP tool ID to bind credentials to (omit the entire mcpCredentials object if not using MCP tools). Only MCP-type tools are accepted; passing an API tool ID will return 400. For API tool credentials, see Two Types of Tool Credentials
mcpCredentials.headers		HTTP headers to send to the MCP Server, enabling the AI to call tools as the user
embedOrigin		The Origin of the embedding page. When the WebChat has "allowed embed domains" configured, server-to-server calls (which lack a browser Origin header) need this field to pass validation

Response (200 OK)

{
  "contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

The returned contactId must be stored in the enterprise system's member data, and passed in when initializing Web Chat on the frontend.

Both sourceId and contactId should be treated as identity credentials: This API is a public endpoint — anyone who knows the webChatId and a user's sourceId can retrieve their contactId; and with the contactId, they can converse as that user and view their conversation history. Therefore:

• Use non-guessable, non-enumerable values for sourceId (e.g., UUID) — do not use sequential IDs, emails, or phone numbers

• Only output contactId to the user themselves on authenticated pages; do not include it in public page source code

• Configure the Allowed Embed Origins list for the Web Chat (provide the domain list to your MaiAgent integration contact) to restrict the origins that can call this API (see Web Chat Embed & SDK)

curl Example

curl -X POST \
  'https://api.maiagent.ai/api/v1/web-chats/{webChatId}/setup-contact-credentials/' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceId": "user-12345",
    "name": "王小明",
    "mcpCredentials": {
      "toolId": "your-mcp-tool-id",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }'

3. Login Flow Integration Point

First Login

Subsequent Login / Token Refresh

Add a new field to the member data table:

Field name	Type	Description
maiagent_contact_id	UUID / VARCHAR(36), nullable	The corresponding MaiAgent Contact ID, stored after the first call

Token expiry handling: When a Token expires or is refreshed, simply call the same API again with the new Token. The same sourceId will automatically update the existing contact's credentials without creating duplicates.

Failures should not block login: If this API call fails, it should not prevent the user from logging into the enterprise system. Make the call asynchronous, log failures, and retry on the next login.

4. Batch Backfill for Existing Users

For large-scale backfills, use batch import instead: Both the dashboard and the API support importing via Excel in a single operation (up to 10,000 rows), with support for query_metadata and API tool credentials. See Contact Batch Import. The per-record approach below is suited for gradual backfilling through the login flow.

When integrating an existing system for the first time, call this API for each existing user to backfill contact mappings:

• Pass each user's sourceId and name, and write the returned contactId back to the member data table

• sourceId is idempotent: the backfill script can be safely re-run without creating duplicate contacts

• If the user's Access Token is not available at the time of backfill, omit mcpCredentials and let the login flow add the credentials when the user next logs in

• Mind the rate limit (30 requests per IP per minute); throttle accordingly for large-scale backfills

5. Sync Contact Profile (Optional)

To sync user information such as department, role, and service tier to MaiAgent (the AI assistant will automatically read this information and provide personalized responses), use the Contact API:

Item	Value
Method	PATCH
URL	https://api.maiagent.ai/api/v1/contacts/{contactId}/
Authentication	Authorization: Api-Key <<Your API Key>>
Content-Type	application/json

{
  "name": "王小明",
  "email": "[e-mail]",
  "metadata": [
    {"key": "Department", "value": "Technical Support"},
    {"key": "Role", "value": "Senior Engineer"},
    {"key": "Service Tier", "value": "Premium"}
  ]
}

• All fields are optional; PATCH only updates the fields provided — fields not included will not be cleared

• The metadata field itself is a full replacement: the provided array will completely overwrite the old one, so include the full metadata array

• You can call this on every login (to keep data current) or only when the user modifies their profile

Why does identity sync not require authentication while profile sync requires an API Key?

setup-contact-credentials is a public endpoint that only returns a UUID. Even if called maliciously, the worst outcome is writing incorrect credentials — the enterprise system's own validation mechanisms will reject invalid Tokens.

However, contact profile data (name, department, attributes) is read by the AI and incorporated into its responses. If this were a public endpoint, a malicious actor could change the name to arbitrary content and feed it directly to the LLM. Therefore, contact profile updates require API Key authentication to ensure only authorized backends can make modifications.

6. Logout and Credential Revocation

There are two things to do at logout — frontend and backend — each with a different scope:

	Frontend MaiAgent.auth.signOut()	Backend credential deletion (this section)
Effect	Chat window returns to anonymous state, clears contextData	Removes the contact's MCP/API tool credentials from MaiAgent
Tool credentials	Does not touch already-written credentials	Credentials are deleted immediately; the AI can no longer call tools as that user
When to call	When the user logs out on the page (see SDK API)	Called by your backend during the logout flow

If your system already revokes the Access Token on your own auth server at logout, the credentials stored by MaiAgent are effectively invalidated. Deleting credentials on the backend is a defense-in-depth measure — it is recommended to do both, to avoid stale Tokens lingering in the system.

Delete Credentials API

Credential type	Method / URL
MCP tool	DELETE /api/v1/contacts/{contactId}/mcp-credentials/{credentialId}/
API tool	DELETE /api/v1/contacts/{contactId}/api-credentials/{credentialId}/

Authentication is Authorization: Api-Key <<Your API Key>> (same as the Contact API). A successful response returns 204 No Content:

curl -X DELETE \
  'https://api.maiagent.ai/api/v1/contacts/{contactId}/mcp-credentials/{credentialId}/' \
  -H 'Authorization: Api-Key <<Your API Key>>'

After deletion, the contact itself, conversation history, and custom attributes are all preserved. When the user logs in again, the login flow's call to setup-contact-credentials will recreate the credentials (the same contact-tool combination is updated/recreated, not duplicated).

Retrieving the credentialId

setup-contact-credentials only returns a contactId and does not include the credential ID. To obtain the credentialId:

• GET /api/v1/contacts/{contactId}/ (Api-Key authentication) — the response includes mcpCredentials and apiCredentials arrays, each entry containing id and tool information. Find the target credential's id by matching tool.id

• When creating credentials via the Contact API, the response is the full contact object — you can store the credential id at creation time

The credential headers in the response may appear in masked form depending on the caller's identity; the revocation flow only needs the id and is not affected.

7. Two Types of Tool Credentials

Contacts can bind dedicated credentials for two types of tools, with different configuration entry points:

	MCP Tool Credentials	API Tool Credentials
Purpose	AI calls MCP Server as the user	AI calls API tools as the user
Sync at login	✅ This page's setup-contact-credentials (no API Key required)	✖ Not supported (passing an API tool ID returns 400)
Contact API	POST /api/v1/contacts/{contactId}/mcp-credentials/	POST /api/v1/contacts/{contactId}/api-credentials/
Update/Delete single	PATCH/DELETE /api/v1/contacts/{contactId}/mcp-credentials/{credentialId}/	PATCH/DELETE /api/v1/contacts/{contactId}/api-credentials/{credentialId}/
Batch import	✖	✅ The API Credentials column in Excel; see Batch Import
Dashboard UI	Contact edit → MCP Credentials (see User Guide)	—

Both credential endpoints of the Contact API require Api-Key authentication, and the body format is the same:

{
  "tool": "<<Tool ID>>",
  "headers": { "Authorization": "Bearer <<User's Token>>" }
}

Repeated calls for the same (contact, tool) combination will update the existing record, not create duplicates. The update/delete endpoints for individual records use the credentialId to identify the target credential; see Retrieving the credentialId for how to obtain it.

8. Error Handling

HTTP Status Code	Possible Cause	Recommended Action
400	Required field missing (e.g., sourceId); Origin not in the allowed embed domain list; toolId does not exist or is unavailable	Check the request body and WebChat settings
404	WebChat ID does not exist	Verify the webChatId is correct
429	Rate limit exceeded (30 requests per IP per minute)	Reduce call frequency and retry
500	Server error	Retry later; if the issue persists, contact the MaiAgent team

9. FAQ

Will repeated calls for the same user create multiple contacts?

No. As long as the sourceId is the same, MaiAgent recognizes it as the same contact and only updates the credentials.

Do I need to retrieve contactId on every login?

The contactId does not change once created and can be persistently stored in the member data table. However, it is still recommended to call this API on each login to update the Token credentials.

What happens if the frontend does not include contactId?

Web Chat will still function, but the AI assistant cannot identify the user, cannot call tools with individual permissions, and conversation history will only be retained per browser (anonymous).

Will the contact and conversation history be deleted after logout?

No. Deleting credentials at logout only removes the tool credentials; the contact itself, conversation history, and custom attributes are all preserved. Full functionality is restored when the user logs in again and this API is called.

What is the difference between contact custom attributes (metadata) and MCP credentials?

MCP credentials are "keys for tools" — they enable the AI to access the enterprise system's API as the user. Custom attributes are "user background information" — they let the AI know who is asking and provide more personalized responses. The two are configured through different APIs and do not affect each other.