メンバーのプロビジョニング：SCIM／招待／SSO

担当者を MaiAgent 組織のメンバーにする3つの方法：SCIM プロビジョニング API（顧客の IT 部門および ISV による運用代行向け）、管理画面からの招待、SSO ログインによる自動プロビジョニング、および MaiGPT のメンバー ID 埋め込みとの連携

MaiAgent の「メンバー」とは、組織内にアカウントを持つ人（従業員や担当者）で、ロール権限、Credits 上限、MaiGPT の利用権限が紐づきます。Web Chat の「連絡先」（お客様、会員、匿名訪問者）とは別の ID 体系です。このページでは、メンバーをプロビジョニングする方法を説明します。主に次の2つの対象者向けです。

• お客様自身の IT 部門：社内の従業員を MaiAgent に一括登録し、退職時に自動で無効化します。

• ISV／システムインテグレーター：顧客組織の運用を代行し、プログラムで顧客の担当者をプロビジョニングした後、メンバー ID 埋め込みを使って MaiGPT を自社システムに埋め込みます。

連絡先（顧客側ユーザー）の作成と同期はこのページの対象外です。ソフトウェアベンダー統合ガイドを参照してください。

「MaiGPT を自社システムに追加する」ことが目的の場合は、まず MaiGPT をシステムに追加するをお読みください。プロビジョニング、トークン発行、埋め込みを一連の流れで説明しています。このページはメンバープロビジョニングの完全なリファレンスです。

用語：SCIM の Group と IdP のグループは、MaiAgent の管理画面ではどちらも「ロール」と呼ばれます。ロールによって、メンバーが利用できる AI Agent、ナレッジベース、および MaiGPT のモデル、ツール、コネクタが決まります。このページでは API の文脈では「グループ」、管理画面の文脈では「ロール」と表記しますが、同じものを指します。

1. 3つの方法の選び方

方法	適しているケース	プロビジョニングのタイミング	退職／無効化	MaiAgent へのログイン方法
SCIM プロビジョニング API（このページの中心）	プログラムまたは IdP で自動化する場合、ISV が運用を代行する場合。IdP がなくても、イベントによるリアルタイム同期または名簿同期ツールを利用できます。	自社システムまたは IdP から能動的にプッシュ	active: false をプッシュして無効化	SSO が必要です（SCIM で作成したアカウントにはパスワードがありません）。メンバー ID 埋め込みのみの場合はログイン不要です。
管理画面からの招待（Email 招待／組織招待リンク）	数十人以内で、システム連携を行わない場合	管理者が管理画面で操作し、相手がメールまたはリンクを開く	管理者が管理画面で無効化	Email からパスワードを設定してログイン、または SSO
SSO ログインによる自動プロビジョニング	従業員が MaiAgent の Web サイトまたは App にログインする場合	初回 SSO ログイン時にメンバーを自動作成	IdP がログインを許可するかどうかに依存します。作成済みメンバーは別途無効化が必要です。	Keycloak／SAML／EIP／Cloudflare Access

3つの方法は併用できます。一般的な組み合わせは、SCIM で名簿を管理＋SSO でログインを管理、または SCIM で名簿を管理＋メンバー ID 埋め込み（従業員は MaiAgent に一切ログインしません）です。

メンバー数は、プランに含まれる組み込み Agent のシート数とメンバーごとの Credits 上限に影響します。一括プロビジョニングの前に、組織プランの容量を確認してください。上限設定については、ユーザーマニュアルのメンバー Credits 上限管理を参照してください。

2. SCIM プロビジョニング API

MaiAgent は組織ごとに SCIM 2.0 の inbound エンドポイントを提供します（ID 同期は Enterprise 機能です。プランに含まれるかどうかは営業担当者にお問い合わせください）。標準的な REST インターフェースであり、Endpoint と Token を Okta、Microsoft Entra ID、JumpCloud などの IdP に設定して自動プッシュさせることも、自社のバックエンドから直接呼び出すこともできます。

連携前のチェックリスト

項目	説明
組織プランに ID 同期が含まれる	Enterprise 機能です。不明な場合は営業担当者にお問い合わせください。
組織 ID と SCIM Token	管理画面の「ID 同期 → SCIM → 接続情報」。Token は一度だけ表示されます。
先にロールを作成し、権限を設定する	SCIM で作成したメンバーはデフォルトロールに追加されず、SCIM が自動作成したロールには権限がありません。メンバーを作成しても何も利用できない場合、ほとんどはこれが原因です。先に管理画面でロール（例：「カスタマーサービス」「マネージャー」）を作成し、MaiGPT の利用権限を含む権限を設定してから、SCIM で同じ名前を指定することをお勧めします。
プランの容量	組み込み Agent のシート数とメンバーごとの Credits 上限
少人数で先にテストする	まず3～5人を作成し、管理画面で氏名、ロール、MaiGPT を利用できるか確認してから全員を登録します。
ログイン方法	メンバー ID 埋め込みのみの場合は不要です。従業員が MaiAgent にログインする場合は SSO が必要です。

既存のアカウントとメンバーへの影響

組織内ですでに Email＋パスワード、管理画面からの招待、または SSO を使って MaiAgent を利用している人がいても、SCIM を有効にしても既存のアカウントは無効になりません。

よくある質問	実際の動作
既存アカウントは引き続きパスワードでログインできますか？	はい。パスワードがないのは SCIM で新規作成したアカウントだけです。既存アカウントのパスワードや SSO の紐付けは変更されません。
SCIM を有効にするとログイン方法が変わりますか？	変わりません。「ID 同期」は SCIM エンドポイントを利用できるかどうかを決めるだけです。ログイン方法は「認証設定」で別途管理します。
重複アカウントが作成されませんか？	作成されません。Email がアカウントのキーです。その Email がすでに同じ組織のメンバーである場合、POST /Users は 409 と既存メンバーの id を返します。別の組織のアカウントである場合は、同じアカウントをこの組織にも追加します。
SCIM で管理されない既存メンバーは無効化されますか？	されません。SCIM は明示的に active: false または DELETE が送られたメンバーだけを無効化します。このサイトの名簿同期ツールも、自身が管理する（externalId がある）メンバーだけを無効化します。
会話履歴や上限の記録は失われますか？	失われません。管理の引き継ぎや無効化でメンバーデータは削除されません。無効化時に、そのメンバーの API Key だけが即時に取り消されます。

変わるのは「SCIM の管理下に入った」メンバーだけです。IdP または自社プログラムが Email で既存メンバーを検索して更新すると、その人は SCIM で管理されます。

• 表示名は IdP／名簿の値で上書きされます。表示名はアカウント単位のため、その人が別の組織にも所属している場合、そちらで表示される名前も変わります。

• SCIM で割り当てたロールは、以後プッシュされるたびに groups[] の内容に従います。管理画面で手動追加したロールは維持されます。

• IdP または名簿で無効化・削除すると、MaiAgent 側でも無効化されます。以前パスワードでログインしていた場合でも、無効化後はこの組織を利用できません。

Okta や Entra ID などの IdP からプッシュする前に、IdP で割り当てる対象範囲を確認してください。範囲内の既存メンバーは SCIM の管理下に入り、以後の利用停止や改名は IdP に従います。まず3～5人（既存メンバー1人を含む）を割り当てて試し、管理画面で氏名、ロール、ログインが正常であることを確認してから範囲を広げることをお勧めします。

有効化と Token の取得

1. 組織の所有者（または「ID 同期管理」権限を持つメンバー）として管理画面にログインし、「組織設定 → ID 同期」に移動して、同期方法に SCIM を選択します。

2. 「接続情報」タブに Endpoint URL（https://api.maiagent.ai/api/v1/scim/<組織 ID> の形式）と Token が表示されます。「Token を再生成」をクリックして新しい Token を取得します。

3. Token は一度だけ表示されます。すぐにサーバーのシークレット管理に保存してください。再生成すると古い Token は即時に無効になります。作成から180日を超えると、管理画面にローテーションの案内が表示されます。

すべてのリクエストに次のヘッダーを付けます。

Authorization: Bearer <SCIM Token>
Content-Type: application/scim+json

各組織には1分あたり100リクエストのレート制限があります。超過すると 429 が返されます。

エンドポイント

メソッド	パス（Endpoint URL の後に付加）	用途
GET	/ServiceProviderConfig、/Schemas、/ResourceTypes	IdP のディスカバリー
GET	/Users?filter=…&startIndex=1&count=50	メンバーの一覧／検索
POST	/Users	メンバーの作成
GET／PUT／PATCH	/Users/{id}	取得／全体置換／部分更新（無効化、改名、externalId の変更）
DELETE	/Users/{id}	メンバーの無効化（後述のセマンティクスを参照）
GET／POST	/Groups	グループ（MaiAgent のロールに対応）の一覧／作成
GET／PUT／PATCH／DELETE	/Groups/{id}	グループ名の変更、メンバーの追加・削除、グループの削除

filter は userName eq "…"、externalId eq "…"、emails.value eq "…"（大文字と小文字を区別しない完全一致）に対応します。Groups は displayName eq "…"、externalId eq "…" に対応します。ページネーションには SCIM 標準の startIndex（1から開始）と count を使用します。

User リソースのフィールド

SCIM フィールド	対応項目	説明
userName	アカウントの Email	必須。MaiAgent のログインアカウントであり、メンバー ID 埋め込みのトークン発行時に使用する email でもあります。作成後は SCIM で変更できません（ライフサイクルを参照）。
emails[primary].value	アカウントの Email	指定した場合は userName より優先されます。
externalId	自社システムの担当者 ID	設定を推奨します。後から filter=externalId eq "…" で検索できます。
name.givenName／name.familyName／displayName	表示名
active	メンバーの有効状態	デフォルトは true です。false にすると無効化されます。
groups[].display	参加するグループ名	既存のグループだけに対応します（先に POST /Groups）。グループとロールを参照してください。

レスポンスには id（MaiAgent のメンバー ID。トークン発行時の memberId としても利用可能）と meta も含まれます。

ライフサイクルのセマンティクス

• 作成：POST /Users は Email をキーとして使用します。その Email の MaiAgent アカウントがすでにある場合（同じ人が別の組織に所属している場合など）、新しいアカウントを作らず、既存アカウントをこの組織に追加します。同じ組織にすでにメンバーがいる場合は 409 を返します。新規作成されたアカウントにはパスワードがありません。MaiAgent の Web サイトへログインするには SSO が必要です。メンバー ID 埋め込みのみを使用する人はログイン不要です。

• 無効化：PATCH で active を false にするか、DELETE /Users/{id} を使用します。どちらも削除ではなく無効化です。メンバーの会話と上限の記録は保持され、API Key は即時に取り消され、ロール権限は無効になり、その後のメンバートークン発行は 404 を返します。再度有効化するとロールは復元されます（dev で検証済み）。組織に所有者が1人しかいない場合、SCIM でその所有者を無効化することはできません。

• 再有効化：PATCH で active を true に戻すか、同じ Email で再度 POST します。

• Email の変更：SCIM では変更できません。PUT／PATCH で異なる userName を指定しても無視されます（Email は組織間で共通のアカウントキーです）。Email を変更するには、管理者が管理画面で変更するか、古いメンバーを無効化して新しい Email でメンバーを作成します（会話履歴は引き継がれません）。

• 更新：PUT は全体を置き換え、PATCH は部分的に更新します。PATCH は {"Operations":[{"op":"replace","path":"active","value":false}]} と {"op":"replace","value":{"active":false}} の両方に対応します（それぞれ Okta と Entra が使用します）。

グループとロール

SCIM の Group は MaiAgent のロールに対応します（メンバーが利用できる AI Agent、ナレッジベース、および MaiGPT のモデル、ツール、コネクタを決定します）。次の3点は必ず理解してください。

1. SCIM で作成したメンバーは「デフォルトロール」に自動追加されません。groups[] で指定したロールにだけ追加され、指定しなければ権限はありません。

2. SCIM が自動作成したロールには権限がありません（POST /Groups で作成したロールには名前しかありません）。メンバーが MaiGPT を利用できるようにするには、管理画面のロール権限で MaiGPT の利用権限を有効にします。MaiGPT ロール利用権限を参照してください。推奨方法：先に管理画面でロールを作成して権限を設定し、その後 SCIM で割り当てます。

3. User の groups[].display は、すでにSCIM とマッピングされたロールだけに対応します。POST／PATCH /Groups の際にマッピングが自動作成されます（デフォルトでは「ロールの自動作成」が有効です）。管理画面で先に作成したロールを SCIM で初めて利用するときは、同じ displayName で一度 PATCH /Groups/{id} を呼び出すとマッピングされます（このサイトの名簿同期ツールとリアルタイム同期 clientにはこの処理が組み込まれています）。IdP を利用する場合は、管理画面の「グループマッピング」タブで IdP の各グループに対応するロールを指定します。

その他の動作：

• PATCH /Groups/{id} は、個別メンバーの add／remove と、メンバー一覧全体の replace に対応します。

• 同じメンバーに SCIM で割り当てたロールは、次回の User PUT／PATCH の groups[] で全体が置き換えられます。管理画面で手動追加したロールには影響しません。

• Group を削除しても、メンバーとロールの関連付けが解除されるだけで、メンバー自体には影響しません。

例

メンバーを作成して「カスタマーサービス」グループに追加します。

curl -X POST "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users" \
  -H "Authorization: Bearer <SCIM Token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[e-mail]",
    "externalId": "emp-10023",
    "name": { "givenName": "Alice", "familyName": "Chen" },
    "displayName": "Alice Chen",
    "active": true,
    "groups": [{ "display": "カスタマーサービス" }]
  }'

退職者を無効化します。

curl -X PATCH "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users/<メンバー ID>" \
  -H "Authorization: Bearer <SCIM Token>" \
  -H "Content-Type: application/scim+json" \
  -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"replace","path":"active","value":false}]}'

自社システムの担当者 ID でメンバーを検索します。

curl "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users?filter=externalId%20eq%20%22emp-10023%22" \
  -H "Authorization: Bearer <SCIM Token>"

IdP を必要としない2つの連携方法

状況	参照するページ
製品が独自のユーザー管理機能を持つ Web サービスである	リアルタイム同期：ユーザーイベント発生時に呼び出す — 追加、変更、無効化のタイミングで呼び出し、メンバーをリアルタイムで一致させます。
名簿が HR システム、Excel、データベースにある	名簿同期ツール：CSV／JSON／データベース — スケジュール実行し、名簿にいる人を作成し、いない人を無効化します。

両方を併用できます。イベントによるリアルタイム同期を中心にし、保険として名簿ツールを1日1回実行して照合します。

IdP からのプッシュ

お客様が Okta、Microsoft Entra ID、JumpCloud などの IdP を利用している場合、Endpoint URL と Token を IdP の SCIM provisioning 設定に入力します。IdP がユーザーとグループを自動でプッシュし、退職者を自動で無効化します。同時に「認証設定」で同じ IdP を SSO（Keycloak または SAML）として設定すると、従業員が直接ログインできます。SAML の設定については、SAML SSO シングルサインオン連携を参照してください。

3. 管理画面からの招待

システム連携を行わない場合は、管理者が管理画面の「組織設定 → メンバー管理」で操作します。

• Email 招待：名簿を入力します（1回につき最大30人）。相手がメールを受信してパスワードを設定するとメンバーになります。

• 組織招待リンク：リンクを従業員に共有し、各自で参加してもらいます。

操作方法については、ユーザーマニュアルのメンバー管理を参照してください。

4. SSO ログインによる自動プロビジョニング

従業員自身が MaiAgent の Web サイト、MaiGPT Web 版、または App にログインする場合は、SSO を設定して会社のアカウントでログインできるようにします。

方法	初回ログイン時の動作
Keycloak、EIP	アカウントを自動作成して組織に追加します。
SAML（ADFS を含む）	アカウントを自動作成します。組織に追加するかどうかは、その認証元の設定によります。連携窓口に確認してください。
Cloudflare Access	認証元の「メンバーを自動プロビジョニング」スイッチによります。無効の場合は既存メンバーだけが許可されます。

設定方法については、ユーザーマニュアルのサードパーティログイン（SSO）と技術ドキュメントのSAML SSO シングルサインオン連携を参照してください。SSO はログイン時にのみメンバーをプロビジョニングします。退職者は SCIM または管理画面で無効化し、IdP によるログイン拒否だけに依存しないでください。

5. MaiGPT メンバー ID 埋め込みとの連携

顧客の運用を代行し、MaiGPT を自社システムに埋め込む ISV の場合、2つの API を次のように連携します。

1. 顧客の利用開始時に、SCIM の POST /Users でメンバーを作成します（userName には従業員の Email、externalId には自社システムの担当者 ID を指定）。そのメンバーを MaiGPT の利用権限を持つグループに追加します。

2. 従業員が自社ページを開いたとき、バックエンドから組織の API Key を使ってメンバートークン発行を呼び出します。email には同じ Email を指定します（または memberId に SCIM が返した id を指定します）。

3. 従業員の退職時に SCIM で無効化します。その後の発行は 404 を返すため、埋め込みページも自動的に利用できなくなります。

従業員が MaiAgent にログインする必要はないため、SSO は不要です。MaiGPT Web 版または App も提供する場合にだけ SSO を追加します。

6. よくある質問

SCIM を接続した後も、既存のアカウントを利用できますか？

はい。SCIM を有効にしても、既存メンバーのパスワード、SSO、ログイン方法は変わりません。重複アカウントが作成されたり、SCIM で管理されていない人が無効化されたりすることもありません。唯一変わるのは、IdP または自社プログラムの管理下に入った既存メンバーについて、その後の氏名、SCIM ロール、有効状態が同期元に従うことです。詳しくは既存のアカウントとメンバーへの影響を参照してください。

「組織メンバー API」を使ってメンバーを直接作成できますか？

管理画面のメンバー API は管理インターフェース用であり、現在は連携事業者には提供していません。プログラムによるプロビジョニングには SCIM を使用してください。

メンバーを作成しましたが、ログイン後に何も利用できず、MaiGPT も開けません。

メンバーが利用できる機能はすべてロールから付与されます。SCIM で作成したメンバーはデフォルトロールに入らず、SCIM が自動作成したロールには権限がないため、「作成できたが何も利用できない」のは通常の結果です。管理画面のロール権限でそのロールの権限（MaiGPT の利用権限を含む）を設定するか、あらかじめロールを作成してから SCIM で割り当ててください。

SCIM で作成したメンバーに招待メールは届きますか？

届きません。SCIM は通知なしでプロビジョニングします。アカウントにはパスワードがなく、通知も送信されません。従業員がログインするには SSO を組み合わせるか、管理画面から Email で招待してください。

1人が複数の組織に所属する場合はどうなりますか？

MaiAgent アカウントは Email をキーとして組織間で共有されますが、メンバー ID は組織ごとに独立しています。ある組織で既存の Email を SCIM により作成すると、そのアカウントがその組織に追加されるだけです。無効化もその組織だけに影響します。表示名はアカウント単位のため、SCIM で改名するとすべての組織に反映されます。