> 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/serve/contacts/contact-credentials-sync.md).
# 連絡先 ID の同期とトークンの更新
企業システムでユーザーを追加するときとログインのたびに、setup-contact-credentials を使用して連絡先の識別情報を同期し、トークン認証情報を更新します
企業システムが Web Chat（[MaiGPT モード](/tech/ja/serve/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 認証情報**に保存し、Agent がそのユーザーとしてツールを呼び出せるようにします
{% hint style="info" %}
連絡先（Contact）の概念と連携全体の流れについては、まず[連絡先（Contact）の紹介と連携](/tech/ja/serve/contacts.md)を参照してください。MCP ツールを使用せず、連絡先の対応関係を作成するだけであれば、そのページの `POST /api/v1/contacts/` の手順も利用できます。このページの API は、ログイン時にトークンも更新する必要がある場合に適しています。
{% endhint %}
### フロントエンドの auth とバックエンド連携の選び方
この API にはフロントエンドから利用する方法もあります。embed SDK の `auth` 設定（[Web Chat の埋め込みと SDK](/tech/ja/serve/web-chat-sdk.md#identify-users)を参照）では、内部でチャットウィンドウが同じ API を自動的に呼び出します。どちらの方法でも同じ連絡先が作成されます（`sourceId` が同じであれば同一人物です）。違いは呼び出し元だけです。
| | フロントエンド auth（SDK が自動実行） | バックエンド連携（このページ） |
| -------- | ------------------------------------------------------------ | ----------------------------------------- |
| 呼び出し元 | ユーザーのブラウザ | 自社のバックエンドサーバー |
| 連携の実装コスト | 低：config に `auth` オブジェクトを追加します | 中：ログイン処理に API 呼び出しと `contactId` の保存を追加します |
| トークンの秘匿性 | `mcpCredentials` がフロントエンドのページに含まれ、ユーザーはソースコードで自分のトークンを確認できます | トークンはフロントエンドを経由しません |
| 適した用途 | ユーザーの識別とデバイス間での会話保持だけが必要な場合 | MCP 認証情報を紐付け、AI がユーザーの権限で API を呼び出す場合 |
## 1. 呼び出しのタイミング
| 状況 | 対応 |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| **ユーザーの追加** | アカウント作成処理でこの API を呼び出し、取得した `contactId` を会員テーブルに保存します |
| **毎回のログイン** | ログイン成功後、Access Token を生成してからフロントエンドに返すまでの間に、この API を**新しいトークン**で呼び出します（同じ `sourceId` であれば自動更新され、重複作成されません） |
| **既存システムの補完（バックフィル）** | 既存ユーザーごとにこの API を呼び出して連絡先を作成します。[既存ユーザーの一括補完](#backfill)を参照してください |
| **トークンの期限切れ / 更新** | 新しいトークンを指定して、この API を再度呼び出します |
| **ログアウト** | フロントエンドで SDK の `signOut()` を呼び出して匿名状態に戻し、バックエンドでその連絡先のツール認証情報を削除します。[ログアウトと認証情報の失効](#logout-revoke)を参照してください |
## 2. API 仕様
| 項目 | 値 |
| ------------ | --------------------------------------------------------------------------------- |
| Method | `POST` |
| URL | `https://api.maiagent.ai/api/v1/web-chats/{webChatId}/setup-contact-credentials/` |
| 認証 | API Key は不要です（公開エンドポイントで、Web Chat 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` | | AI がそのユーザーとしてツールを呼び出すために、MCP Server に送信する HTTP headers です |
| `embedOrigin` | | 埋め込みページの Origin です。Web Chat に「埋め込みを許可するドメイン」が設定されている場合、**サーバー間**の呼び出し（ブラウザの Origin header がない場合）では、このフィールドを指定して検証を通過する必要があります |
### 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 などの**推測も列挙もできない**値を使用し、連番、Email、電話番号は使用しないでください
* `contactId` は**ログイン後**のページでユーザー本人にだけ渡し、公開ページのソースコードに含めないでください
* Web Chat に**埋め込みを許可するドメイン**のリストを設定し（管理者が管理画面の会話プラットフォームの基本設定で入力します）、この API を呼び出せる送信元を制限してください（[Web Chat の埋め込みと SDK](/tech/ja/serve/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..."
}
}
}'
```
## 3. ログイン処理への組み込み位置
### 初回ログイン
```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: Agent がユーザーの識別情報に基づいて対応します
```
### 2 回目以降のログイン／トークン更新
```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＋新しいトークン）
Note over MA: 同じ連絡先として認識します
認証情報のみを更新し、重複作成しません
MA-->>BE: contactId（同じ値です）
BE-->>U: ログイン結果（既存の contactId を使用します）
```
会員テーブルに、次のフィールドを追加することをお勧めします。
| フィールド名 | 型 | 説明 |
| --------------------- | --------------------------- | -------------------------------------- |
| `maiagent_contact_id` | UUID / VARCHAR(36)、nullable | 対応する MaiAgent の連絡先 ID です。初回呼び出し後に保存します |
{% hint style="success" %}
**トークンの期限切れへの対応：** トークンの期限切れや更新時には、新しいトークンを指定して同じ API を再度呼び出すだけです。同じ `sourceId` であれば、既存の連絡先の認証情報が自動更新され、重複作成されません。
{% endhint %}
{% hint style="warning" %}
**失敗してもログインを妨げないでください：** この API の呼び出しに失敗しても、ユーザーの企業システムへのログインを妨げないようにしてください。非同期で呼び出し、失敗時はログに記録して次回のログイン時に再試行することをお勧めします。
{% endhint %}
## 4. 既存ユーザーの一括補完
{% hint style="success" %}
**大量の補完には一括インポートをお勧めします**。管理画面と API の両方で、Excel による一括インポート（上限 10,000 行）に対応しています。query\_metadata と API ツールの認証情報も同時に取り込めます。[連絡先の一括インポート](/tech/ja/serve/contacts.md#bulk-import)を参照してください。以下の個別呼び出しは、ログイン処理を通じて段階的に補完する場合に適しています。
{% endhint %}
既存システムを初めて連携するときは、既存ユーザーごとにこの API を呼び出して連絡先の対応関係を作成できます。
```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["各ユーザーの次回ログイン時に
ログイン処理でトークン認証情報を追加します"]
```
* 各ユーザーの `sourceId` と `name` を指定し、返された `contactId` を会員テーブルに保存してください
* `sourceId` は冪等です。補完スクリプトを安全に再実行でき、連絡先は重複作成されません
* 補完時にユーザーの Access Token を取得できない場合は、`mcpCredentials` を省略し、そのユーザーの次回ログイン時にログイン処理で追加できます
* レート制限（IP ごとに毎分 30 回）に注意し、大量に補完する場合は呼び出しの間隔を調整してください
## 5. 連絡先情報の同期（任意）
ユーザーの部署、ロール、サービスレベルなどの情報を MaiAgent に同期する場合は、連絡先 API を使用してください。Agent はこれらの情報を自動的に読み取り、パーソナライズした応答を提供します。
| 項目 | 値 |
| ------------ | ------------------------------------------------------ |
| Method | `PATCH` |
| URL | `https://api.maiagent.ai/api/v1/contacts/{contactId}/` |
| 認証 | `Authorization: Api-Key <<ご利用の API Key>>` |
| Content-Type | `application/json` |
```json
{
"name": "山田太郎",
"email": "xiaoming.wang@example.com",
"metadata": [
{"key": "部署", "value": "テクニカルサポート部"},
{"key": "ロール", "value": "シニアエンジニア"},
{"key": "サービスレベル", "value": "Premium"}
]
}
```
* すべてのフィールドは任意です。PATCH は指定したフィールドのみ更新し、省略したフィールドは消去しません
* `metadata` フィールド自体は**全体を置き換えます**。送信した配列で既存の配列が完全に上書きされるため、metadata 配列全体を指定してください
* 毎回のログイン時に呼び出して情報を最新に保つことも、ユーザーがプロフィールを変更したときだけ呼び出すこともできます
識別情報の同期は認証不要なのに、連絡先情報の同期には API Key が必要なのはなぜですか？
`setup-contact-credentials` は公開エンドポイントで、UUID を 1 つ返すだけです。悪意のある呼び出しが行われても、誤った認証情報が書き込まれるだけで、企業システム自体の認証機構が無効なトークンを拒否します。
一方、連絡先情報（氏名、部署、属性）は AI が読み取り、回答に反映します。公開エンドポイントにすると、攻撃者が氏名を任意の内容に書き換え、そのまま LLM に送信できます。そのため、連絡先情報の更新には **API Key 認証**が必要です。これにより、認可されたバックエンドだけが変更できます。
## 6. ログアウトと認証情報の失効
ログアウト時には、フロントエンドとバックエンドで 1 つずつ対応が必要で、それぞれ作用する範囲が異なります。
| | フロントエンドの `MaiAgent.auth.signOut()` | バックエンドでのツール認証情報の削除（この節） |
| ---------- | ---------------------------------------------------------------------------------- | ---------------------------------------- |
| 作用 | チャットウィンドウを匿名状態に戻し、`contextData` を消去します | MaiAgent からその連絡先の MCP／API ツール認証情報を削除します |
| ツール認証情報 | 保存済みの認証情報は**変更しません** | 認証情報は即座に削除され、AI はそのユーザーとしてツールを呼び出せなくなります |
| 呼び出しのタイミング | ユーザーがページ上でログアウトしたときです（[SDK API](/tech/ja/serve/web-chat-sdk.md#api-auth)を参照してください） | ログアウト処理中にバックエンドから呼び出します |
ログアウト時に自社の認証サーバーで Access Token を失効させている場合、MaiAgent に保存された認証情報はすでに無効です。バックエンドでの認証情報の削除は多層防御として機能します。無効なトークンがシステムに残らないよう、併せて実行することをお勧めします。
```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` だけなので、影響はありません。
## 7. 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/serve/contacts.md#bulk-import)を参照してください |
| 管理画面 UI | 連絡先の編集 → MCP 認証情報（[ユーザーマニュアル](https://docs.maiagent.ai/build/tools/setup-contacts-mcp-credentials)を参照してください） | — |
連絡先 API の 2 つの認証情報エンドポイントは、どちらも `Api-Key` 認証が必要で、body の形式は同じです。
```json
{
"tool": "<<ツール ID>>",
"headers": { "Authorization": "Bearer <<ユーザーのトークン>>" }
}
```
同じ（連絡先、ツール）の組み合わせで繰り返し呼び出すと、重複作成せずに更新します。個別の更新／削除エンドポイントでは `credentialId` で対象を指定します。取得方法については[credentialId の取得](#get-credential-id)を参照してください。
## 8. エラー処理
| HTTP ステータスコード | 考えられる原因 | 推奨される対応 |
| ------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------- |
| `400` | 必須フィールド（`sourceId` など）がありません。Origin が埋め込みを許可するドメインのリストに含まれていません。`toolId` が存在しないか、利用できません | request body と Web Chat の設定を確認してください |
| `404` | Web Chat ID が存在しません | `webChatId` が正しいことを確認してください |
| `429` | レート制限を超えています（IP ごとに毎分 30 回） | 呼び出し頻度を下げて再試行してください |
| `500` | サーバーエラーです | 時間をおいて再試行し、問題が続く場合は MaiAgent チームにお問い合わせください |
## 9. よくある質問
同じユーザーに対して繰り返し呼び出すと、複数の連絡先が作成されますか？
いいえ。`sourceId` が同じであれば、MaiAgent は同じ連絡先として認識し、認証情報のみを更新します。
contactId は毎回のログイン時に取得し直す必要がありますか？
`contactId` は作成後に変わらず、会員テーブルに永続保存できます。ただし、トークン認証情報を更新するため、毎回のログイン時にこの API を呼び出すことをお勧めします。
フロントエンドで contactId を指定しないとどうなりますか？
Web Chat は動作しますが、Agent はユーザーを識別できず、個人の権限でツールを呼び出せません。会話履歴もブラウザ単位でのみ保持されます（匿名状態です）。
ログアウト後に連絡先と会話履歴は削除されますか？
いいえ。[ログアウト時の認証情報の削除](#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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/tech/ja/serve/contacts/contact-credentials-sync.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.