> 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/ja/authorization-integration/contact-credentials-sync.md). # コンタクト ID 同期とトークン更新 企業システムが Web Chat（[MaiGPT モード](/tech/ja/api-integration/web-chat-sdk/web-chat-maigpt-mode.md)を含む）を自社プロダクトに埋め込んだ後、AI に「誰が質問しているか」を認識させる必要があります。これにより、AI はそのユーザーの会話履歴を遡ることができ、MCP ツールを呼び出す際に**そのユーザーの権限**で企業システムの API にアクセスできます。 `setup-contact-credentials` この API は1回の呼び出しで2つのことを完了します： 1. 「企業システムアカウント ↔ MaiAgent コンタクト（Contact）」の対応関係を**作成または更新**します 2. そのユーザーの Access Token を**コンタクト MCP クレデンシャル**に書き込み、AI アシスタントがそのユーザーの身元でツールを呼び出せるようにします {% hint style="info" %} コンタクト（Contact）の概念と全体の連携フローについては、まず[コンタクト (Contact) の紹介と連携](/tech/ja/authorization-integration/contacts.md)をご参照ください。MCP ツールを使用せず、コンタクトの対応関係の作成のみが必要な場合は、そのページの `POST /api/v1/contacts/` フローでも対応できます。本ページの API は「ログイン時に Token を同期更新する」シナリオに適しています。 {% endhint %} ### フロントエンド auth とバックエンド連携の選び方 この API にはフロントエンド版もあります：embed SDK の `auth` 設定（[Web Chat 埋め込みと SDK](/tech/ja/api-integration/web-chat-sdk.md#identify-users) を参照）の内部では、チャットウィンドウが自動的に同じ API を呼び出しています。どちらの方法でも作成されるのは同一のコンタクトです（`sourceId` が同じであれば同一人物）。違いは誰が呼び出すかだけです： | | フロントエンド auth（SDK 自動） | バックエンド連携（本ページ） | | ---------- | --------------------------------------------------------------- | ---------------------------------------- | | 呼び出し元 | ユーザーのブラウザ | お客様のバックエンドサーバー | | 統合コスト | 低：config に `auth` オブジェクトを1つ追加 | 中：ログインフローに API 呼び出し1回＋`contactId` の保存を追加 | | Token の機密性 | `mcpCredentials` がフロントエンドページに表示され、ユーザーがソースコードで自分の token を確認できます | Token はフロントエンドを経由しません | | 適したケース | ユーザーの識別、クロスデバイスでの会話保持のみ | MCP クレデンシャルを紐付けて AI がユーザー権限で API を呼び出す場合 | ## 一、呼び出しタイミング | シナリオ | 方法 | | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | **ユーザー新規追加** | アカウント作成フローで本 API を呼び出し、取得した `contactId` を会員データテーブルに保存します | | **毎回のログイン** | ログイン成功後、Access Token を生成してからフロントエンドに返す前に本 API を呼び出し、**新しい Token** を渡します（同一の `sourceId` は自動的に更新され、重複作成されません） | | **既存システムの補完（バックフィル）** | 既存ユーザーに対して本 API を1件ずつ呼び出してコンタクトの対応を補完します。[既存ユーザーのバッチ補完](#backfill)を参照してください | | **Token の期限切れ / リフレッシュ** | 本 API を再度呼び出して新しい Token を渡すだけです | | **ログアウト** | フロントエンドで SDK の `signOut()` を呼び出して匿名状態に戻ります。バックエンドで該当連絡先のツール認証情報を削除します。[ログアウトと認証情報の無効化](#logout-revoke)を参照してください | ## 二、API 仕様 | 項目 | 値 | | ------------ | --------------------------------------------------------------------------------- | | Method | `POST` | | URL | `https://api.maiagent.ai/api/v1/web-chats/{webChatId}/setup-contact-credentials/` | | 認証 | API Key 不要（公開エンドポイント、WebChat ID のみ必要） | | Content-Type | `application/json` | | レート制限 | IP あたり毎分 30 回 | {% hint style="info" %} URL は SaaS 環境（`api.maiagent.ai`）を例としています。プライベートクラウド / オンプレミスデプロイの場合は、お客様の環境の API ドメインに置き換えてください。 {% endhint %} ### Request Body ```json { "sourceId": "user-12345", "name": "田中太郎", "mcpCredentials": { "toolId": "your-mcp-tool-id", "headers": { "Authorization": "Bearer <<ユーザーの Access Token>>" } } } ``` | フィールド | 必須 | 説明 | | ------------------------ | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sourceId` | ✅ | 企業システムにおけるユーザーの一意識別子。**同一の `sourceId` で重複呼び出しすると、重複作成ではなく更新されます。** 推測不可能な値（UUID など）を使用してください。下記のセキュリティに関する注意を参照してください | | `name` | | ユーザーの表示名。MaiAgent 管理画面のコンタクト一覧に表示されます。未指定の場合、デフォルトは `Anonymous` です。**コンタクトの初回作成時のみ有効**です。その後の名前更新には[コンタクト情報の同期](#sync-contact-profile)をご利用ください | | `mcpCredentials.toolId` | | クレデンシャルを紐付ける **MCP ツール** の ID（MCP ツールを使用しない場合は `mcpCredentials` 全体を省略できます）。MCP タイプのツールのみ受け付けます。API ツール ID を指定すると 400 が返されます。API ツールのクレデンシャルについては[ツールクレデンシャルの2つのタイプ](#credential-types)を参照してください | | `mcpCredentials.headers` | | MCP Server に送信する HTTP ヘッダー。AI がそのユーザーの身元でツールを呼び出せるようにします | | `embedOrigin` | | 埋め込みページの Origin。WebChat に「許可する埋め込みドメイン」が設定されている場合、**サーバー間**通信（ブラウザの Origin ヘッダーがない）ではこのフィールドを指定して検証を通過する必要があります | ### Response（200 OK） ```json { "contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` 返された `contactId` は**企業システムの会員データに保存**する必要があります。フロントエンドで Web Chat を初期化する際に渡します。 {% hint style="danger" %} **`sourceId` と `contactId` はどちらも身元クレデンシャルとして扱うべきです**：この API は公開エンドポイントであり、`webChatId` と誰かの `sourceId` を知っていれば、その人の `contactId` を取得できます。また、`contactId` を取得すれば、そのユーザーの身元で会話でき、会話履歴を閲覧できます。そのため： * `sourceId` には**推測不可能、列挙不可能**な値（UUID など）を使用し、連番、メールアドレス、電話番号は使用しないでください * `contactId` は**ログイン後**のページでのみ、そのユーザー本人にのみ出力し、公開ページのソースコードには含めないでください * Web Chat に**許可された埋め込みドメイン**リストを設定してください（ドメインリストを MaiAgent 担当窓口にご提供ください）。本 API を呼び出せるソースを制限できます（[Web Chat 埋め込みと SDK](/tech/ja/api-integration/web-chat-sdk.md#embed-origin-allowlist) を参照） {% endhint %} ### curl の例 ```bash 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..." } } }' ``` ## 三、ログインフローの統合箇所 ### 初回ログイン ```mermaid sequenceDiagram actor U as ユーザー participant FE as 企業システムフロントエンド participant BE as 企業システムバックエンド participant MA as MaiAgent U->>FE: ログイン FE->>BE: アカウントとパスワード BE->>BE: 認証成功、Access Token を生成 rect rgb(230, 242, 255) Note over BE,MA: 追加された統合ステップ BE->>MA: POST setup-contact-credentials
（sourceId＋name＋mcpCredentials） MA-->>BE: contactId BE->>BE: contactId を会員データテーブルに保存 end BE-->>FE: ログイン結果（contactId を含む） FE->>MA: Web Chat を読み込み（config に contactId を含める） MA-->>U: AI アシスタントがユーザーの身元でサービスを提供 ``` ### 以降のログイン／Token リフレッシュ ```mermaid sequenceDiagram actor U as ユーザー participant BE as 企業システムバックエンド participant MA as MaiAgent U->>BE: ログイン BE->>BE: 新しい Access Token を生成 BE->>MA: POST setup-contact-credentials
（同じ sourceId＋新しい Token） Note over MA: 同一コンタクトとして認識
クレデンシャルのみ更新、重複作成なし MA-->>BE: contactId（同じ値） BE-->>U: ログイン結果（既存の contactId を使用） ``` 会員データテーブルにフィールドを1つ追加することを推奨します： | フィールド名 | 型 | 説明 | | --------------------- | --------------------------- | ------------------------------------ | | `maiagent_contact_id` | UUID / VARCHAR(36)、nullable | 対応する MaiAgent コンタクト ID。初回呼び出し後に保存します | {% hint style="success" %} **Token 期限切れの処理：** Token が期限切れまたはリフレッシュされた場合、同じ API を再度呼び出して新しい Token を渡すだけです。同一の `sourceId` は既存コンタクトのクレデンシャルを自動的に更新し、重複作成されません。 {% endhint %} {% hint style="warning" %} **失敗時にログインをブロックしないでください：** この API の呼び出しが失敗した場合、ユーザーの企業システムへのログインをブロックすべきではありません。非同期呼び出しとして設定し、失敗時にはログを記録して次回ログイン時にリトライすることを推奨します。 {% endhint %} ## 四、既存ユーザーのバッチ補完 {% hint style="success" %} **大量の補完にはバッチインポートの利用を推奨します**：管理画面と API の両方で Excel による一括インポート（上限 10,000 行）をサポートしており、query\_metadata と API ツールクレデンシャルも同時に取り込めます。[コンタクトのバッチインポート](/tech/ja/authorization-integration/contacts.md#bulk-import)を参照してください。以下の1件ずつ呼び出す方法は、ログインフローに沿って段階的に補完する場合に適しています。 {% endhint %} 既存システムの初回連携時、既存ユーザーに対して本 API を1件ずつ呼び出してコンタクトの対応を補完できます： ```mermaid flowchart TD A[既存ユーザー一覧を取得] --> B["POST setup-contact-credentials
（sourceId＋name、mcpCredentials は一旦なし）"] B --> C[contactId を会員データテーブルに書き戻し] C --> D{次のレコードがあるか？} D -->|あり| E["ペースを制御
（IP あたり毎分 30 回）"] E --> B D -->|なし| F[補完完了] F -.-> G["各ユーザーの次回ログイン時に
ログインフローで Token クレデンシャルを補完"] ``` * 各ユーザーの `sourceId` と `name` を1件ずつ渡し、返された `contactId` を会員データテーブルに書き戻します * `sourceId` は冪等です：補完スクリプトは安全に再実行でき、重複コンタクトは作成されません * 補完時にユーザーの Access Token が取得できない場合は、`mcpCredentials` を省略し、そのユーザーの次回ログイン時にログインフローで補完できます * レート制限（IP あたり毎分 30 回）に注意し、大量の補完時はペースを制御してください ## 五、コンタクト情報の同期（オプション） ユーザーの部門、ロール、サービスレベルなどの情報を MaiAgent に同期する場合（AI アシスタントはこれらの情報を自動的に読み取り、パーソナライズされた応答を提供します）、コンタクト API を使用してください： | 項目 | 値 | | ------------ | ------------------------------------------------------ | | Method | `PATCH` | | URL | `https://api.maiagent.ai/api/v1/contacts/{contactId}/` | | 認証 | `Authorization: Api-Key <<お客様の API Key>>` | | Content-Type | `application/json` | ```json { "name": "田中太郎", "email": "taro.tanaka@example.com", "metadata": [ {"key": "部門", "value": "テクニカルサポート部"}, {"key": "ロール", "value": "シニアエンジニア"}, {"key": "サービスレベル", "value": "Premium"} ] } ``` * すべてのフィールドは任意です。PATCH は送信されたフィールドのみ更新し、未送信のフィールドはクリアされません * `metadata` フィールド自体は**全量置換**です：送信された配列が既存のものを完全に上書きしますので、完全な metadata 配列を渡してください * 毎回のログイン時に呼び出す（データを最新に保つ）ことも、ユーザーが個人情報を変更した時のみ呼び出すこともできます
なぜ身元同期は認証不要で、データ同期には API Key が必要なのですか？ `setup-contact-credentials` は公開エンドポイントであり、UUID を1つ返すだけです。悪意のある呼び出しがあっても、誤ったクレデンシャルが書き込まれるだけで、企業システム自体の認証メカニズムが無効な Token をブロックします。 一方、コンタクトデータ（氏名、部門、属性）は AI に読み取られ、回答に反映されます。公開エンドポイントにした場合、悪意のある者が名前を任意の内容に変更し、直接 LLM に送り込むことが可能になります。そのため、コンタクトデータの更新には **API Key 認証**が必要であり、認可されたバックエンドのみが変更できるようにしています。
## 六、ログアウトと認証情報の無効化 ログアウト時にはフロントエンドとバックエンドの2つの処理があり、作用範囲が異なります： | | フロントエンド `MaiAgent.auth.signOut()` | バックエンドでのツール認証情報の削除（本節） | | --------- | ------------------------------------------------------------------------------------ | ----------------------------------------- | | 作用 | チャットウィンドウが匿名状態に戻り、`contextData` がクリアされます | MaiAgent から該当連絡先の MCP／API ツール認証情報を削除します | | ツール認証情報 | 書き込み済みの認証情報には**影響しません** | 認証情報が即座に削除され、AI はそのユーザーの身元でツールを呼び出せなくなります | | 呼び出しタイミング | ユーザーがページ上でログアウトした時（[SDK API](/tech/ja/api-integration/web-chat-sdk.md#api-auth) を参照） | ログアウトフロー内でお客様のバックエンドから呼び出します | お客様のシステムでログアウト時に自社の認証サーバーで該当 Access Token を無効化済みであれば、MaiAgent に保存された認証情報は既に無効です。バックエンドでの認証情報削除は多層防御として、失効した Token がシステムに残留することを防ぐために併せて実施することを推奨します。 ```mermaid sequenceDiagram actor U as ユーザー participant FE as 企業システムフロントエンド participant BE as 企業システムバックエンド participant MA as MaiAgent U->>FE: ログアウト FE->>MA: MaiAgent.auth.signOut() Note over FE,MA: チャットウィンドウが匿名状態に戻ります FE->>BE: ログアウトリクエスト BE->>BE: 自社の Access Token を無効化 BE->>MA: DELETE 該当連絡先の mcp-credentials／api-credentials MA-->>BE: 204 No Content Note over MA: 認証情報を削除。連絡先と会話履歴は保持
次回ログイン時に身元同期 API で再作成 ``` ### 認証情報削除 API | 認証情報の種類 | Method / URL | | ------- | --------------------------------------------------------------------- | | MCP ツール | `DELETE /api/v1/contacts/{contactId}/mcp-credentials/{credentialId}/` | | API ツール | `DELETE /api/v1/contacts/{contactId}/api-credentials/{credentialId}/` | 認証方式は `Authorization: Api-Key <<お客様の API Key>>`（連絡先 API と同じ）で、成功時は `204 No Content` を返します： ```bash curl -X DELETE \ 'https://api.maiagent.ai/api/v1/contacts/{contactId}/mcp-credentials/{credentialId}/' \ -H 'Authorization: Api-Key <<お客様の API Key>>' ``` 削除後も連絡先自体、会話履歴、カスタム属性はすべて保持されます。ユーザーが次回ログインした際に、ログインフローで `setup-contact-credentials` を呼び出すことで認証情報が再作成されます（同一の連絡先とツールの組み合わせでは更新／再作成となり、重複は発生しません）。 ### credentialId の取得 `setup-contact-credentials` は `contactId` のみを返し、認証情報 ID は含まれません。`credentialId` を取得するには以下の方法があります： * `GET /api/v1/contacts/{contactId}/`（`Api-Key` 認証）のレスポンスに含まれる `mcpCredentials` と `apiCredentials` 配列に、各認証情報の `id` と `tool` 情報が含まれます。`tool.id` で対象の認証情報の `id` を特定してください * [連絡先 API で認証情報を作成](#credential-types)した際のレスポンスは完全な連絡先オブジェクトであり、作成時点で認証情報の `id` を保存できます レスポンス内の認証情報 `headers` は、呼び出し元の身元によってマスク表示される場合があります。無効化フローでは `id` のみが必要であり、影響はありません。 ## 七、ツール認証情報の2つのタイプ コンタクトには2種類のツールの専用クレデンシャルを紐付けることができます。設定の入り口が異なります： | | MCP ツールクレデンシャル | API ツールクレデンシャル | | -------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | 用途 | AI がユーザーの身元で MCP Server を呼び出します | AI がユーザーの身元で API ツールを呼び出します | | ログイン時の同期 | ✅ 本ページの `setup-contact-credentials`（API Key 不要） | ✖ サポートされていません（API ツール ID を指定すると 400） | | 連絡先 API | `POST /api/v1/contacts/{contactId}/mcp-credentials/` | `POST /api/v1/contacts/{contactId}/api-credentials/` | | 個別更新／削除 | `PATCH`／`DELETE /api/v1/contacts/{contactId}/mcp-credentials/{credentialId}/` | `PATCH`／`DELETE /api/v1/contacts/{contactId}/api-credentials/{credentialId}/` | | バッチインポート | ✖ | ✅ Excel の `API Credentials` 列、[バッチインポート](/tech/ja/authorization-integration/contacts.md#bulk-import)を参照 | | 管理画面 UI | コンタクト編集 → MCP クレデンシャル（[ユーザーマニュアル](https://docs.maiagent.ai/tools/setup-contacts-mcp-credentials)を参照） | — | コンタクト API の2つのクレデンシャルエンドポイントはどちらも `Api-Key` 認証が必要です。body のフォーマットは同じです： ```json { "tool": "<<ツール ID>>", "headers": { "Authorization": "Bearer <<ユーザーの Token>>" } } ``` 同一の組み合わせ（連絡先、ツール）で重複呼び出しすると更新になり、重複作成されません。個別の更新／削除エンドポイントは `credentialId` で対象の認証情報を指定します。取得方法は[credentialId の取得](#get-credential-id)を参照してください。 ## 八、エラーハンドリング | HTTP ステータスコード | 考えられる原因 | 推奨される対処 | | ------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- | | `400` | 必須フィールドの欠落（`sourceId` など）、Origin が許可する埋め込みドメインリストに含まれていない、`toolId` が存在しないまたは利用不可 | request body と WebChat の設定を確認してください | | `404` | WebChat ID が存在しません | `webChatId` が正しいか確認してください | | `429` | レート制限を超過（IP あたり毎分 30 回） | 呼び出し頻度を下げてからリトライしてください | | `500` | サーバー異常 | しばらく待ってからリトライし、継続する場合は MaiAgent チームにお問い合わせください | ## 九、よくある質問
同一ユーザーで重複呼び出しすると、複数のコンタクトが作成されますか？ いいえ。`sourceId` が同じであれば、MaiAgent は同一コンタクトとして認識し、クレデンシャルのみ更新します。
contactId は毎回ログインするたびに再取得する必要がありますか？ `contactId` は作成後に変わることはなく、会員データテーブルに永続的に保存できます。ただし、毎回のログイン時に Token クレデンシャルを更新するために本 API を呼び出すことを推奨します。
フロントエンドで contactId を渡さないとどうなりますか？ Web Chat は引き続き動作しますが、AI アシスタントはユーザーの身元を識別できず、個人の権限でツールを呼び出すことができません。会話履歴もブラウザ単位でのみ保持されます（匿名）。
ログアウト後に連絡先と会話履歴は削除されますか？ いいえ。[ログアウト時の認証情報削除](#logout-revoke)ではツール認証情報のみが削除されます。連絡先自体、会話履歴、カスタム属性はすべて保持されます。次回ログイン時に本 API を呼び出すことで、完全な機能が回復されます。
連絡先のカスタム属性（metadata）と MCP 認証情報の違いは何ですか？ MCP クレデンシャルは「ツールの鍵」です。AI がユーザーの身元で企業システムの API にアクセスできるようにします。カスタム属性は「ユーザーの背景情報」です。AI が誰が質問しているかを把握し、よりパーソナライズされた回答を提供します。両者は異なる API で設定され、互いに影響しません。
--- # 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/ja/authorization-integration/contact-credentials-sync.md?ask=&goal= ``` `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.