> 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/en/identity-and-access/member-provisioning.md).
# Member Provisioning: SCIM / Invitations / SSO
Three ways to add your personnel as MaiAgent organization members—SCIM provisioning API (for customer IT teams and ISV-managed organizations), admin console invitations, and automatic provisioning thr
MaiAgent **members** are people with accounts in an organization (employees and staff), with role permissions, Credits quotas, and MaiGPT access. They use a separate identity system from Web Chat **contacts** (your customers, registered users, and anonymous visitors). This page explains how to provision **members** and is intended for two audiences:
* **Customer IT teams**: Add company employees to MaiAgent in bulk and automatically deactivate them when they leave.
* **ISVs / system integrators**: Manage customer organizations, provision their personnel programmatically, and use [member identity embedding](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md#member-embed) to embed MaiGPT in your own system.
Creating and synchronizing contacts (customer-side users) is outside the scope of this page. See the [Software Vendor Integration Guide](/tech/en/serve/vendor-integration-guide.md).
{% hint style="info" %}
If your goal is to add MaiGPT to your system, start with [Add MaiGPT to Your System](/tech/en/work/maigpt-system-integration-guide.md), which connects provisioning, token exchange, and embedding into one flow. This page provides the complete reference for member provisioning.
{% endhint %}
```mermaid
flowchart TD
A["Your personnel need to become organization members"] --> B{"How many people, and do you need automation?"}
B -->|"A few dozen or fewer, no integration"| C["Admin console invitations (Section 3)"]
B -->|"Automation needed"| D{"Do you have an IdP that supports SCIM?
(Okta, Entra ID, JumpCloud)"}
D -->|"Yes"| E["IdP pushes to SCIM endpoints (Section 2)"]
D -->|"No"| F{"Where is your roster?"}
F -->|"Your product manages users"| G["Real-time sync: call from events"]
F -->|"HR system, Excel, database"| H["Roster sync tool: run on a schedule"]
C --> I{"Do employees need to log in to the MaiAgent website or app?"}
E --> I
G --> I
H --> I
I -->|"Yes"| J["Also configure SSO (Section 4)"]
I -->|"No, they only use MaiGPT in your system"| K["Member identity embedding (Section 5)"]
```
**Terminology**: SCIM Groups and IdP groups are called **roles** in the MaiAgent admin console. They determine which AI Agents and knowledge bases members can use, as well as their access to MaiGPT models, tools, and connectors. This page uses “group” in API contexts and “role” in admin console contexts; both refer to the same thing.
## 1. Choosing Among the Three Options
| Method | Best for | When provisioning happens | Offboarding / deactivation | How personnel log in to MaiAgent |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **SCIM provisioning API** (the focus of this page) | Automation through code or an IdP; ISV-managed organizations. Works without an IdP too: [event-based real-time sync](/tech/en/identity-and-access/member-provisioning/member-event-sync.md) or the [roster sync tool](/tech/en/identity-and-access/member-provisioning/member-roster-sync.md) | Your system or IdP actively pushes updates | Push `active: false` to deactivate | Requires SSO (accounts created through SCIM have no password); login is unnecessary if you only use member identity embedding |
| **Admin console invitations** (Email invitations / organization invitation links) | A few dozen people or fewer, without integration | An administrator sends invitations in the console; recipients open the Email or click the link | An administrator deactivates members in the console | Set a password through Email, or use SSO |
| **Automatic provisioning through SSO login** | Employees already need to log in to the MaiAgent website or app | A member is created automatically at the first SSO login | Depends on whether the IdP allows login; existing members must be deactivated separately | Keycloak / SAML / EIP / Cloudflare Access |
You can combine these options. Common combinations are **SCIM for the roster + SSO for login**, or **SCIM for the roster + member identity embedding** (employees never log in to MaiAgent).
{% hint style="info" %}
The member count affects built-in Agent seats and per-member Credits quota allocation in your plan. Check your organization's plan capacity before bulk provisioning. For quota settings, see [Member Credits Quota Management](https://docs.maiagent.ai/others/credits/member-credit-quota) in the user manual.
{% endhint %}
## 2. SCIM Provisioning API
MaiAgent provides inbound SCIM 2.0 endpoints for each organization (identity synchronization is an enterprise feature; contact sales to confirm whether your plan includes it). These are standard REST endpoints: enter the Endpoint and Token into an IdP such as Okta, Microsoft Entra ID, or JumpCloud for automatic pushes, or call them directly from your own backend.
### Pre-integration Checklist
| Item | Description |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your organization plan includes identity synchronization | An enterprise feature; contact sales if unsure |
| Organization ID and SCIM Token | Admin console: “Identity Sync → SCIM → Connection Information”; the Token is shown only once |
| **Create roles and configure permissions first** | **Members created through SCIM do not join the default role, and roles automatically created through SCIM have no permissions**. This is the cause in most cases where a provisioned member cannot use anything. Create roles in the console first (such as “Customer Support” or “Manager”) and configure their permissions, including MaiGPT access, then assign them through SCIM using the same names |
| Plan capacity | Built-in Agent seats and per-member Credits quotas |
| Start with a small test | Create three to five members, check their names, roles, and MaiGPT access in the console, then provision everyone |
| Login method | Skip this if you only use member identity embedding; SSO is required if employees log in to MaiAgent |
### What Happens to Existing Accounts and Members
If people in your organization already use MaiAgent through Email and password, admin console invitations, or SSO, enabling SCIM **does not invalidate their existing accounts**:
| Common question | Actual behavior |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Can they still log in with their existing password? | Yes. Only accounts **newly created** through SCIM have no password. Existing passwords and SSO bindings remain unchanged |
| Does enabling SCIM change the login method? | No. “Identity Sync” only controls whether SCIM endpoints are available; login methods are managed separately in “Authentication Settings” |
| Will a duplicate account be created? | No. Accounts are keyed by Email: if that Email is already a member of this organization, `POST /Users` returns `409` with the existing member's `id`; if the account belongs to another organization, the same account is added to this organization |
| Will existing members outside SCIM management be deactivated? | No. SCIM only deactivates members explicitly sent `active: false` or `DELETE`. The [roster sync tool](/tech/en/identity-and-access/member-provisioning/member-roster-sync.md) on this site also only deactivates members it manages (those with an `externalId`) |
| Will conversation or quota records disappear? | No. Taking over management or deactivating a member does not delete member data; deactivation only immediately revokes that member's API Key |
**Only members taken over by SCIM are affected**. Once an IdP or your program finds an existing member by Email and updates them, that person becomes SCIM-managed:
* The display name is overwritten with the value from the IdP or roster. Display names are account-level, so if the person also belongs to other organizations, their name changes there too.
* Roles assigned through SCIM follow `groups[]` in each subsequent push; roles added manually in the console are retained.
* Deactivating or removing the person in the IdP or roster also deactivates them in MaiAgent. Even if they previously logged in with a password, they can no longer use this organization after deactivation.
{% hint style="warning" %}
Before pushing from an IdP such as Okta or Entra ID, check which personnel are assigned in the IdP: **existing members within that scope will become IdP-managed**, and subsequent deactivations and name changes will follow the IdP. Start with three to five people (including an existing member), verify names, roles, and login in the console, then expand the scope.
{% endhint %}
### Enable SCIM and Obtain a Token
1. Log in to the console as the organization owner, go to “Organization Settings → Identity Sync”, and select **SCIM** as the synchronization method. Only owners can switch the synchronization method and regenerate Tokens; members whose roles have “Identity Sync Permission” can only view settings. For console instructions, see [Console Operations When SCIM Is Selected](https://docs.maiagent.ai/org/sso/identity-sync#scim-setup) in the user manual.
2. The “Connection Information” tab shows the **Endpoint URL** (such as `https://api.maiagent.ai/api/v1/scim/<組織 ID>`) and Token. Click “Regenerate Token” to obtain a new Token.
3. The Token is **shown only once**. Immediately save it in your server's secret manager. Regenerating it immediately invalidates the previous Token; the console reminds you to rotate it once it is more than 180 days old.
Include the following in every request:
```
Authorization: Bearer
Content-Type: application/scim+json
```
Each organization is limited to 100 requests per minute; exceeding the limit returns `429`.
### Endpoints
| Method | Path (appended to the Endpoint URL) | Purpose |
| ---------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `GET` | `/ServiceProviderConfig`, `/Schemas`, `/ResourceTypes` | IdP discovery |
| `GET` | `/Users?filter=…&startIndex=1&count=50` | List / query members |
| `POST` | `/Users` | Create a member |
| `GET` / `PUT` / `PATCH` | `/Users/{id}` | Read / update a resource / partially update (deactivate, rename, change externalId) |
| `DELETE` | `/Users/{id}` | Deactivate a member (see semantics below) |
| `GET` / `POST` | `/Groups` | List / create groups (corresponding to MaiAgent roles) |
| `GET` / `PUT` / `PATCH` / `DELETE` | `/Groups/{id}` | Rename groups, add/remove members, delete groups |
`filter` supports `userName eq "…"`, `externalId eq "…"`, and `emails.value eq "…"` (case-insensitive equality matching). Groups support `displayName eq "…"` and `externalId eq "…"`. Pagination uses the SCIM standard `startIndex` (starting at 1) and `count`.
### User Resource Fields
| SCIM field | Mapping | Description |
| ---------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userName` | Account Email | **Required**; the MaiAgent login account, and the `email` used when exchanging a token for [member identity embedding](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md#member-embed). **Cannot be changed through SCIM after creation** (see lifecycle) |
| `emails[primary].value` | Account Email | Takes precedence over `userName` when provided |
| `externalId` | Personnel ID in your system | Recommended; later query the member with `filter=externalId eq "…"` |
| `name.givenName` / `name.familyName` / `displayName` | Display name | |
| `active` | Member activation status | Defaults to `true`; `false` deactivates the member |
| `groups[].display` | Names of groups to join | Only matches existing groups (create them with `POST /Groups` first); see [Groups and Roles](#scim-groups) |
The response also includes `id` (the MaiAgent member ID, which can be used as `memberId` for token exchange) and `meta`.
### Lifecycle Semantics
* **Create**: `POST /Users` uses Email as the key. Personnel removed from the organization by an administrator are not automatically restored when the IdP resends a request; creation returns `403`, and an administrator must invite them again first. If the Email already has a MaiAgent account (for example, the same person belongs to another organization), that account is added to this organization without creating another account. If the member already exists in the same organization, the request returns `409`. Newly created accounts **have no password** and can only log in to the MaiAgent website through SSO; personnel who only use member identity embedding do not need to log in.
* **Deactivate**: Use `PATCH` to set `active` to `false`, or `DELETE /Users/{id}`. Both **deactivate rather than delete**: the member's conversation and quota records are retained, their API Key is immediately revoked, and their role permissions become ineffective. Subsequent member token exchanges return `404`; reactivating the member restores their roles. SCIM will not deactivate the organization's sole remaining owner.
* **Reactivate**: Use `PATCH /Users/{id}` with the existing member ID and set `active` back to `true`. Deactivation does not delete the member, so another `POST /Users` with the same Email still returns `409` and does not reactivate them; use the `id` in the response to update them.
* **Change Email**: Email cannot be changed through SCIM. A different `userName` in `PUT` / `PATCH` is ignored (Email is the account key across organizations). To change an Email, an administrator must edit it in the console, or deactivate the old member and create a new member with the new Email (conversation history is not carried over).
* **Update**: Use `PATCH` when changing individual fields such as activation status. When parsing `PUT`, omitted `displayName` and `externalId` fields default to empty strings, and omitted `active` defaults to `true`; this may overwrite existing names or `externalId` values, or reactivate members. Omitting `groups` retains existing group assignments. `PATCH` accepts both `{"Operations":[{"op":"replace","path":"active","value":false}]}` and `{"op":"replace","value":{"active":false}}` formats (Okta and Entra each use one).
### Groups and Roles
SCIM Groups correspond to MaiAgent **roles** (which determine access to AI Agents, knowledge bases, and MaiGPT models, tools, and connectors). You need to know three things:
1. **Members created through SCIM do not automatically join the “default role”**. They only join roles specified in `groups[]`; without any specified roles, they have no permissions.
2. **Roles automatically created through SCIM have no permissions** (`POST /Groups` creates a role with only a name). To let members use MaiGPT, enable MaiGPT access in the console's role permissions. See [MaiGPT Role Permissions](https://docs.maiagent.ai/org/roles/maigpt-role-permissions). **Recommended approach**: Create roles and configure their permissions in the console first, then assign them through SCIM using the same names.
3. **A User's `groups[].display` only matches roles already mapped to SCIM**. Mapping is created automatically during `POST` / `PATCH /Groups` (“Automatically Create Roles” is enabled by default). For a role created in the console, send `PATCH /Groups/{id}` once with the same `displayName` to establish the mapping before its first use through SCIM (the [roster sync tool](/tech/en/identity-and-access/member-provisioning/member-roster-sync.md) and [real-time sync client](/tech/en/identity-and-access/member-provisioning/member-event-sync.md) on this site already include this step). For IdP integration, specify which role each IdP group maps to in the console's “Group Mapping” tab.
Other behavior:
* `PATCH /Groups/{id}` supports `add` / `remove` for individual members and `replace` for the full member list.
* A member's SCIM-assigned roles are replaced in full by `groups[]` in the next User `PUT` / `PATCH`; roles added manually in the console are unaffected.
* Deleting a Group only removes associations between members and the role; it does not affect the members themselves.
### Examples
Create a member and add them to the “Customer Support” group:
```bash
curl -X POST "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users" \
-H "Authorization: Bearer " \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "alice@acme.com",
"externalId": "emp-10023",
"name": { "givenName": "Alice", "familyName": "Chen" },
"displayName": "Alice Chen",
"active": true,
"groups": [{ "display": "Customer Support" }]
}'
```
Deactivate an employee who has left:
```bash
curl -X PATCH "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users/<成員 ID>" \
-H "Authorization: Bearer " \
-H "Content-Type: application/scim+json" \
-d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"replace","path":"active","value":false}]}'
```
Look up a member by their personnel ID in your system:
```bash
curl "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users?filter=externalId%20eq%20%22emp-10023%22" \
-H "Authorization: Bearer "
```
### Two Integration Options Without an IdP
| Your situation | Which page to use |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your product is a web service with its own user management | [Real-time Sync: Call from User Events](/tech/en/identity-and-access/member-provisioning/member-event-sync.md)—call when a user is added, modified, or deactivated to keep members in sync immediately |
| Your personnel roster is in an HR system, Excel, or a database | [Roster Sync Tool: CSV / JSON / Database](/tech/en/identity-and-access/member-provisioning/member-roster-sync.md)—run on a schedule to create members present in the roster and deactivate those absent |
You can combine both: use event-based real-time sync as the primary method and reconcile the roster daily as a safeguard.
### Push from an IdP
If a customer uses an IdP such as Okta, Microsoft Entra ID, or JumpCloud, enter the Endpoint URL and Token in the IdP's SCIM provisioning settings. The IdP automatically pushes users and groups and deactivates departing employees. Also configure the same IdP for SSO (Keycloak or SAML) in “Authentication Settings” so employees can log in directly. For SAML configuration, see [SAML SSO Integration](/tech/en/identity-and-access/sso-overview/saml-sso.md).
## 3. Admin Console Invitations
Without an integration, administrators use “Organization Settings → Member Management” in the console:
* **Email invitations**: Enter a list (up to 100 recipients at a time); recipients become members after setting a password through the Email.
* **Organization invitation link**: Share the link with employees so they can join themselves.
For instructions, see [Member Management](https://docs.maiagent.ai/org/overview/member) in the user manual.
## 4. Automatic Provisioning Through SSO Login
If employees need to log in to the MaiAgent website, MaiGPT web version, or app themselves, configure SSO so they can use their company accounts:
| Method | At the first login |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keycloak, EIP, SAML (including ADFS) | Automatically creates an account (or links an existing account with the same Email) and adds it to the organization configured with this authentication source |
| Cloudflare Access | Controlled by the authentication source's “Automatically Provision Members” switch; when disabled, only existing members are allowed through |
{% hint style="warning" %}
Automatic provisioning does not restore membership for people removed by an administrator who have not yet been invited again. EIP rejects login when synchronizing roles during login; Cloudflare Access also rejects rejoining even with “Automatically Provision Members” enabled. SAML / Keycloak do not automatically add that person back to the authentication source's organization; this does not mean login to other organizations is always denied. To restore access, have an administrator [invite the member again](https://docs.maiagent.ai/org/overview/member) first, then use the original login method.
This differs from directory synchronization **deactivation**: after SCIM deactivation, [reactivate](#scim-lifecycle) using the original member ID; do not treat resending a creation request as a recovery method. New members who have never joined the organization still follow the automatic provisioning rules in the table above.
{% endhint %}
For configuration, see [Third-party Login (SSO)](https://docs.maiagent.ai/org/sso) in the user manual and [SAML SSO Integration](/tech/en/identity-and-access/sso-overview/saml-sso.md) in the technical documentation. SSO only provisions members at login. Deactivate departing employees through SCIM or the console instead of relying solely on the IdP to deny login: IdP denial only blocks SSO; accounts that already have passwords can still log in with them, and the member's API Key remains valid. For console instructions, see [Offboarding and Deactivating Members](https://docs.maiagent.ai/org/sso#offboarding) in the user manual.
## 5. Connecting to MaiGPT Member Identity Embedding
For ISVs managing customers and embedding MaiGPT in their own systems, connect the two APIs as follows:
1. When onboarding a customer, create members with SCIM `POST /Users` (`userName` is the employee's Email; `externalId` is their personnel ID in your system) and add them to a group with MaiGPT access.
2. When an employee opens your page, call [member token exchange](/tech/en/work/maigpt-system-integration-guide/maigpt-integration.md#member-embed-issue) from your backend using the organization's API Key. Set `email` to the same Email (or `memberId` to the `id` returned by SCIM).
3. When the employee leaves, deactivate them through SCIM. Subsequent token exchanges return `404`, making the embedded page inaccessible.
Employees never need to log in to MaiAgent, so SSO is unnecessary. Add SSO if you also want to allow access to the MaiGPT web version or app.
## 6. Frequently Asked Questions
Can existing accounts still be used after integrating SCIM?
Yes. Enabling SCIM does not change existing members' passwords, SSO, or login methods, create duplicate accounts, or deactivate people outside SCIM management. The only change is that existing members taken over by an IdP or your program subsequently synchronize their names, SCIM roles, and deactivation status with that source. See [What Happens to Existing Accounts and Members](#scim-existing-accounts) for details.
Can I create members directly through the “Organization Member API”?
The console's member API is intended for the management interface and is currently unavailable to integration partners. Use SCIM for programmatic provisioning.
A member has been created, but cannot use anything after login / cannot open MaiGPT?
All member capabilities come from roles. Members created through SCIM do not join the default role, and automatically created SCIM roles have no permissions, so having no access after creation is expected. Configure the role's permissions (including MaiGPT access) in the console, or create the role first and then assign it through SCIM.
Do members created through SCIM receive invitation Emails?
No Email is sent. SCIM provisions silently: accounts have no password and receive no notification. Use SSO for employee login, or use admin console Email invitations instead.
What if a person belongs to multiple organizations?
MaiAgent accounts are keyed by Email and shared across organizations, while membership is separate for each organization. Creating a member with an existing Email through SCIM only adds that account to the specified organization; deactivation also only affects that organization. Display names are account-level, so renaming through SCIM is reflected in all organizations.
---
# 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/en/identity-and-access/member-provisioning.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.