コンタクト ID 同期とトークン更新

企業システムでのユーザー新規追加時および毎回のログイン時に、setup-contact-credentials を通じて連絡先の身元同期と Token 認証情報の更新を行います

企業システムが Web Chat（MaiGPT モードを含む）を自社プロダクトに埋め込んだ後、AI に「誰が質問しているか」を認識させる必要があります。これにより、AI はそのユーザーの会話履歴を遡ることができ、MCP ツールを呼び出す際にそのユーザーの権限で企業システムの API にアクセスできます。

setup-contact-credentials この API は1回の呼び出しで2つのことを完了します：

1. 「企業システムアカウント ↔ MaiAgent コンタクト（Contact）」の対応関係を作成または更新します

2. そのユーザーの Access Token をコンタクト MCP クレデンシャルに書き込み、AI アシスタントがそのユーザーの身元でツールを呼び出せるようにします

コンタクト（Contact）の概念と全体の連携フローについては、まずコンタクト (Contact) の紹介と連携をご参照ください。MCP ツールを使用せず、コンタクトの対応関係の作成のみが必要な場合は、そのページの POST /api/v1/contacts/ フローでも対応できます。本ページの API は「ログイン時に Token を同期更新する」シナリオに適しています。

フロントエンド auth とバックエンド連携の選び方

この API にはフロントエンド版もあります：embed SDK の auth 設定（Web Chat 埋め込みと SDK を参照）の内部では、チャットウィンドウが自動的に同じ 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件ずつ呼び出してコンタクトの対応を補完します。既存ユーザーのバッチ補完を参照してください
Token の期限切れ / リフレッシュ	本 API を再度呼び出して新しい Token を渡すだけです
ログアウト	フロントエンドで SDK の signOut() を呼び出して匿名状態に戻ります。バックエンドで該当連絡先のツール認証情報を削除します。ログアウトと認証情報の無効化を参照してください

二、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 回

URL は SaaS 環境（api.maiagent.ai）を例としています。プライベートクラウド / オンプレミスデプロイの場合は、お客様の環境の API ドメインに置き換えてください。

Request Body

{
  "sourceId": "user-12345",
  "name": "田中太郎",
  "mcpCredentials": {
    "toolId": "your-mcp-tool-id",
    "headers": {
      "Authorization": "Bearer <<ユーザーの Access Token>>"
    }
  }
}

フィールド	必須	説明
sourceId	✅	企業システムにおけるユーザーの一意識別子。同一の sourceId で重複呼び出しすると、重複作成ではなく更新されます。 推測不可能な値（UUID など）を使用してください。下記のセキュリティに関する注意を参照してください
name		ユーザーの表示名。MaiAgent 管理画面のコンタクト一覧に表示されます。未指定の場合、デフォルトは Anonymous です。コンタクトの初回作成時のみ有効です。その後の名前更新にはコンタクト情報の同期をご利用ください
mcpCredentials.toolId		クレデンシャルを紐付ける MCP ツール の ID（MCP ツールを使用しない場合は mcpCredentials 全体を省略できます）。MCP タイプのツールのみ受け付けます。API ツール ID を指定すると 400 が返されます。API ツールのクレデンシャルについてはツールクレデンシャルの2つのタイプを参照してください
mcpCredentials.headers		MCP Server に送信する HTTP ヘッダー。AI がそのユーザーの身元でツールを呼び出せるようにします
embedOrigin		埋め込みページの Origin。WebChat に「許可する埋め込みドメイン」が設定されている場合、サーバー間通信（ブラウザの Origin ヘッダーがない）ではこのフィールドを指定して検証を通過する必要があります

Response（200 OK）

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

返された contactId は企業システムの会員データに保存する必要があります。フロントエンドで Web Chat を初期化する際に渡します。

sourceId と contactId はどちらも身元クレデンシャルとして扱うべきです：この API は公開エンドポイントであり、webChatId と誰かの sourceId を知っていれば、その人の contactId を取得できます。また、contactId を取得すれば、そのユーザーの身元で会話でき、会話履歴を閲覧できます。そのため：

• sourceId には推測不可能、列挙不可能な値（UUID など）を使用し、連番、メールアドレス、電話番号は使用しないでください

• contactId はログイン後のページでのみ、そのユーザー本人にのみ出力し、公開ページのソースコードには含めないでください

• Web Chat に許可された埋め込みドメインリストを設定してください（ドメインリストを MaiAgent 担当窓口にご提供ください）。本 API を呼び出せるソースを制限できます（Web Chat 埋め込みと SDK を参照）

curl の例

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..."
      }
    }
  }'

三、ログインフローの統合箇所

初回ログイン

以降のログイン／Token リフレッシュ

会員データテーブルにフィールドを1つ追加することを推奨します：

フィールド名	型	説明
maiagent_contact_id	UUID / VARCHAR(36)、nullable	対応する MaiAgent コンタクト ID。初回呼び出し後に保存します

Token 期限切れの処理： Token が期限切れまたはリフレッシュされた場合、同じ API を再度呼び出して新しい Token を渡すだけです。同一の sourceId は既存コンタクトのクレデンシャルを自動的に更新し、重複作成されません。

失敗時にログインをブロックしないでください： この API の呼び出しが失敗した場合、ユーザーの企業システムへのログインをブロックすべきではありません。非同期呼び出しとして設定し、失敗時にはログを記録して次回ログイン時にリトライすることを推奨します。

四、既存ユーザーのバッチ補完

大量の補完にはバッチインポートの利用を推奨します：管理画面と API の両方で Excel による一括インポート（上限 10,000 行）をサポートしており、query_metadata と API ツールクレデンシャルも同時に取り込めます。コンタクトのバッチインポートを参照してください。以下の1件ずつ呼び出す方法は、ログインフローに沿って段階的に補完する場合に適しています。

既存システムの初回連携時、既存ユーザーに対して本 API を1件ずつ呼び出してコンタクトの対応を補完できます：

• 各ユーザーの 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

{
  "name": "田中太郎",
  "email": "[e-mail]",
  "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 を参照）	ログアウトフロー内でお客様のバックエンドから呼び出します

お客様のシステムでログアウト時に自社の認証サーバーで該当 Access Token を無効化済みであれば、MaiAgent に保存された認証情報は既に無効です。バックエンドでの認証情報削除は多層防御として、失効した Token がシステムに残留することを防ぐために併せて実施することを推奨します。

認証情報削除 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 を返します：

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 で認証情報を作成した際のレスポンスは完全な連絡先オブジェクトであり、作成時点で認証情報の 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 列、バッチインポートを参照
管理画面 UI	コンタクト編集 → MCP クレデンシャル（ユーザーマニュアルを参照）	—

コンタクト API の2つのクレデンシャルエンドポイントはどちらも Api-Key 認証が必要です。body のフォーマットは同じです：

{
  "tool": "<<ツール ID>>",
  "headers": { "Authorization": "Bearer <<ユーザーの Token>>" }
}

同一の組み合わせ（連絡先、ツール）で重複呼び出しすると更新になり、重複作成されません。個別の更新／削除エンドポイントは credentialId で対象の認証情報を指定します。取得方法はcredentialId の取得を参照してください。

八、エラーハンドリング

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 アシスタントはユーザーの身元を識別できず、個人の権限でツールを呼び出すことができません。会話履歴もブラウザ単位でのみ保持されます（匿名）。

ログアウト後に連絡先と会話履歴は削除されますか？

いいえ。ログアウト時の認証情報削除ではツール認証情報のみが削除されます。連絡先自体、会話履歴、カスタム属性はすべて保持されます。次回ログイン時に本 API を呼び出すことで、完全な機能が回復されます。

連絡先のカスタム属性（metadata）と MCP 認証情報の違いは何ですか？

MCP クレデンシャルは「ツールの鍵」です。AI がユーザーの身元で企業システムの API にアクセスできるようにします。カスタム属性は「ユーザーの背景情報」です。AI が誰が質問しているかを把握し、よりパーソナライズされた回答を提供します。両者は異なる API で設定され、互いに影響しません。