Member Provisioning: SCIM/Invitations/SSO

Three ways to make your personnel members of a MaiAgent organization: the SCIM provisioning API (for customer IT teams and managed services from ISVs), admin-console invitations, and automatic provisi

A MaiAgent “member” is a person with an account in an organization (such as an employee or administrator), associated with role permissions, a Credits quota, and MaiGPT access. This is separate from Web Chat “contacts” (your customers, members, and anonymous visitors). This page explains how to provision members and is intended for two audiences:

• Your own IT team: Add company employees to MaiAgent in batches and automatically deactivate them when they leave.

• ISVs/system integrators: Manage customer organizations, programmatically provision customer personnel, and then embed MaiGPT in your system with member identity embedding.

Creating and synchronizing contacts (customer-side users) is outside the scope of this page. See the Software Vendor Integration Guide.

If your goal is to “add MaiGPT to our system,” first read Add MaiGPT to Your System. It connects provisioning, token issuance, and embedding into a single flow; this page is the complete reference for member provisioning.

Terminology: A SCIM Group and an IdP group are both called a “role” in the MaiAgent admin console. A role determines which AI Agents and knowledge bases a member can use, as well as the models, tools, and connectors available in MaiGPT. This page uses “group” in an API context and “role” in an admin-console context; they refer to the same thing.

1. Choosing among the three approaches

Approach	Best for	Provisioning time	Employee departure/deactivation	How personnel sign in to MaiAgent
SCIM provisioning API (focus of this page)	Programmatic or IdP automation; managed services from ISVs. An IdP is not required: use real-time event synchronization or the roster sync tool.	Your system or IdP proactively pushes data	Push active: false to deactivate	Requires SSO (accounts created by SCIM have no password); signing in is unnecessary when only using member identity embedding
Admin-console invitation (Email invitation/organization invitation link)	Up to a few dozen people with no desired integration	An administrator acts in the console, and the recipient opens an email or link	An administrator deactivates the member in the console	Set a password through Email, or use SSO
Automatic provisioning through SSO login	Employees who already sign in to the MaiAgent website or app	A member is created automatically upon the first SSO login	Depends on whether the IdP permits login; existing members must be deactivated separately	Keycloak/SAML/EIP/Cloudflare Access

The three approaches can be combined. Common combinations are SCIM for roster management + SSO for login, or SCIM for roster management + member identity embedding (employees never sign in to MaiAgent).

The number of members affects the built-in Agent seats and per-member Credits quota included in your plan. Before provisioning in batches, confirm your organization plan capacity. For quota settings, see Member Credits Quota Management in the user manual.

2. SCIM provisioning API

MaiAgent provides each organization with an inbound SCIM 2.0 endpoint (identity synchronization is an Enterprise feature; contact Sales to confirm whether it is included in your plan). It is a standard REST interface. You can enter its Endpoint and Token in an IdP such as Okta, Microsoft Entra ID, or JumpCloud and let the IdP push automatically, or call it directly from your own backend.

Pre-integration checklist

Item	Description
Organization plan includes identity synchronization	Enterprise feature; contact Sales if unsure
Organization ID and SCIM Token	Admin console: “Identity synchronization → SCIM → Connection information.” The Token is shown only once.
Create roles and configure permissions first	Members created through SCIM are not added to the default role, and roles created automatically through SCIM have no permissions—this is the cause in most cases where a new member cannot use anything. We recommend first creating roles in the admin console (such as “Customer Service” and “Manager”) and configuring permissions, including MaiGPT access, then assigning those exact names through SCIM.
Plan capacity	Built-in Agent seats and per-member Credits quota
Start with a small test	Create three to five people first, then confirm their names, roles, and MaiGPT access in the admin console before provisioning everyone.
Login method	Can be skipped if only using member identity embedding; employees who need to sign in to MaiAgent require SSO.

What happens to existing accounts and members?

If people in the 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 an existing account still sign in with its password?	Yes. Only accounts newly created through SCIM have no password; passwords and SSO bindings on existing accounts are untouched.
Does enabling SCIM change the login method?	No. “Identity synchronization” only determines whether the SCIM endpoint is available; login methods are managed separately under “Authentication settings.”
Will a duplicate account be created?	No. Email is the account key. If the Email is already a member of this organization, POST /Users returns 409 together with the existing member's id. If the account belongs to another organization, the same account is simply added to this organization.
Are old members not managed by SCIM deactivated?	No. SCIM only deactivates members explicitly sent active: false or DELETE. This site's roster sync tool also deactivates only members it manages (those with an externalId).
Are conversation and quota records lost?	No. Taking over or deactivating a member does not delete member data. Only that member's API Key is revoked immediately upon deactivation.

Only members “taken over by SCIM” will change: after your IdP or program finds an existing member by Email and updates that member, SCIM manages the person:

• The display name is overwritten by the IdP/roster value. Display names are account-level, so if the person also belongs to another organization, that organization sees the changed name too.

• Roles assigned through SCIM follow the groups[] value in every subsequent push. Roles added manually in the admin console are retained.

• If the person is deactivated or removed from the IdP or roster, the member is deactivated in MaiAgent as well. Even if the member previously used password login, they can no longer use this organization after deactivation.

Before pushing from an IdP such as Okta or Entra ID, confirm the IdP assignment scope: existing members within the scope will be taken over and subsequent suspensions and name changes will follow the IdP. We recommend first assigning three to five people (including one existing member), confirming their names, roles, and login in the admin console, and only then expanding the scope.

Enable SCIM and obtain a Token

1. Sign in to the admin console as the organization owner (or a member with the “Manage identity synchronization” permission), go to “Organization settings → Identity synchronization,” and select SCIM as the synchronization method.

2. The “Connection information” tab shows the Endpoint URL (in the form https://api.maiagent.ai/api/v1/scim/<Organization ID>) and Token. Click “Regenerate Token” to obtain a new Token.

3. The Token is shown only once. Store it immediately in your server's secret manager. The old Token becomes invalid immediately after regeneration. The admin console reminds you to rotate it after 180 days.

Include these headers in every request:

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

Each organization is limited to 100 requests per minute. Requests beyond the limit return 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/replace fully/update partially (deactivate, rename, or 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 a group, add/remove members, or delete it

filter supports userName eq "…", externalId eq "…", and emails.value eq "…" (case-insensitive equality). Groups support displayName eq "…" and externalId eq "…". Pagination uses the standard SCIM startIndex (starting at 1) and count.

User resource fields

SCIM field	Maps to	Description
userName	Account Email	Required. This is the MaiAgent login account and is also the email used when issuing a token for member identity embedding. It cannot be changed through SCIM after creation (see Lifecycle).
emails[primary].value	Account Email	Takes precedence over userName when supplied
externalId	Personnel ID in your system	Recommended; you can later query it 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	Maps only to existing groups (first use POST /Groups). See Groups and roles.

The response also includes an id (the MaiAgent member ID, which can also be used as the memberId for token issuance) and meta.

Lifecycle semantics

• Create: POST /Users uses Email as the key. If the Email already has a MaiAgent account (for example, the same person belongs to another organization), the existing account is added to this organization rather than creating another account. If the member already exists in this organization, it returns 409. Newly created accounts have no password and can sign in to the MaiAgent website only through SSO. Personnel who only use member identity embedding do not need to sign in.

• Deactivate: Use PATCH to set active to false, or use DELETE /Users/{id}. Both deactivate rather than delete: the member's conversations and quota records remain, the member's API Key is revoked immediately, role permissions cease to apply, and subsequent member token issuance returns 404. Roles are restored when the member is reactivated (verified in dev). SCIM cannot deactivate the owner if the organization has only one owner.

• Reactivate: Use PATCH to set active back to true, or POST the same Email again.

• Change Email: Email cannot be changed through SCIM—userName with a different value in PUT/PATCH is ignored (Email is the cross-organization account key). To change Email, an administrator must update it in the admin console, or deactivate the old member and create a member with the new Email (conversation history does not carry over).

• Update: PUT replaces the entire resource and PATCH updates it partially. PATCH accepts both {"Operations":[{"op":"replace","path":"active","value":false}]} and {"op":"replace","value":{"active":false}} (used by Okta and Entra respectively).

Groups and roles

A SCIM Group corresponds to a MaiAgent role (which determines which AI Agents and knowledge bases members can use, plus the models, tools, and connectors available in MaiGPT). You must know these three points:

1. Members created through SCIM are not automatically added to the “default role.” They are added only to roles named in groups[]; without one, they have no permissions.

2. Roles created automatically through SCIM have no permissions (a role created with POST /Groups has only a name). To let members use MaiGPT, enable MaiGPT access in the role permissions in the admin console. See MaiGPT Role Access Permissions. Recommended approach: Create roles and permissions in the admin console first, then assign them through SCIM.

3. A User's groups[].display maps only to a role that is already mapped to SCIM. The mapping is created automatically during POST/PATCH /Groups (“Automatically create roles” is enabled by default). To map a role created in the admin console the first time SCIM uses it, call PATCH /Groups/{id} once with the same displayName (this site's roster sync tool and real-time sync client do this automatically). With an IdP, specify which role each IdP group maps to on the “Group mapping” tab in the admin console.

Other behavior:

• PATCH /Groups/{id} supports add/remove for individual members and replace for the entire member list.

• Roles assigned to the same member through SCIM are fully replaced by groups[] in the next User PUT/PATCH. Roles added manually in the admin console are unaffected.

• Deleting a Group only removes the association between members and the role; it does not affect the members themselves.

Examples

Create a member and add them to the “Customer Service” group:

curl -X POST "https://api.maiagent.ai/api/v1/scim/<Organization 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": "Customer Service" }]
  }'

Deactivate an employee who leaves:

curl -X PATCH "https://api.maiagent.ai/api/v1/scim/<Organization ID>/Users/<Member 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}]}'

Look up a member by the personnel ID in your system:

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

Two integration approaches that do not require an IdP

Your situation	See this page
Your product is a Web service with its own user management	Real-time sync: Call during user events—call it when a user is added, updated, or deactivated to keep members synchronized in real time.
Your roster is in an HR system, Excel, or a database	Roster sync tool: CSV/JSON/database—run it on a schedule to create people present in the roster and deactivate those absent from it.

You can use both: make event-driven real-time synchronization the primary method and run the roster tool once a day for reconciliation 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 then pushes users and groups automatically and deactivates departing employees. Also configure the same IdP as SSO (Keycloak or SAML) under “Authentication settings” so employees can sign in directly. For SAML settings, see SAML SSO Integration.

3. Admin-console invitations

When no integration is used, an administrator works in “Organization settings → Member management” in the admin console:

• Email invitation: Enter a roster (up to 30 at once). Recipients become members after opening the email and setting a password.

• Organization invitation link: Share the link with employees so they can join on their own.

For instructions, see Member Management in the user manual.

4. Automatic provisioning through SSO login

When employees need to sign in to the MaiAgent website, the MaiGPT web app, or the app themselves, configure SSO so they can use their corporate accounts:

Method	On first login
Keycloak, EIP	Automatically creates an account and adds it to the organization
SAML (including ADFS)	Automatically creates an account; whether it joins the organization depends on the authentication source's settings. Confirm with your integration contact.
Cloudflare Access	Depends on the authentication source's “Automatically provision members” toggle. When disabled, only existing members are allowed.

For setup instructions, see Third-party Login (SSO) in the user manual and the technical documentation's SAML SSO Integration. SSO provisions a member only upon login. Use SCIM or the admin console to deactivate departing employees; do not rely only on the IdP denying login.

5. Connecting to MaiGPT member identity embedding

For ISVs that manage customers and want to embed MaiGPT in their own system, the two APIs work together as follows:

1. When onboarding a customer, use SCIM POST /Users to create a member (userName is the employee Email and externalId is the personnel ID in your system), and add the member to a group with MaiGPT access.

2. When an employee opens your page, your backend calls member token issuance with the organization's API Key. Set email to the same Email (or set memberId to the id returned by SCIM).

3. When an employee leaves, deactivate the member through SCIM. Subsequent issuance returns 404, so the embedded page naturally stops working.

Employees never need to sign in to MaiAgent, so SSO is unnecessary. Add SSO only if you also want to make the MaiGPT web app or app available.

6. FAQ

Can existing accounts still be used after connecting SCIM?

Yes. Enabling SCIM does not change existing members' passwords, SSO, or login methods. It does not create duplicate accounts or deactivate people not managed by SCIM. The only change is that for an existing member taken over by your IdP or program, their name, SCIM roles, and activation status subsequently synchronize with the source. See What happens to existing accounts and members? for details.

Can I create members directly with the “organization member API”?

The admin console's member API is intended for the management interface and is not currently available to integrators. Use SCIM for programmatic provisioning.

The member has been created, but cannot use anything after login/MaiGPT will not open. Why?

All member capabilities come from roles. Members created through SCIM do not enter the default role, while roles created automatically through SCIM have no permissions. Therefore, “created successfully but nothing is available” is the expected result until permissions are configured. Configure that role's permissions (including MaiGPT access) in the admin console, or create the role first and then assign it through SCIM.

Do members created through SCIM receive an invitation email?

No. SCIM provisions silently: the account has no password and no notification is sent. Pair it with SSO to let employees sign in, or use an Email invitation from the admin console instead.

What if one person belongs to multiple organizations?

MaiAgent accounts use Email as the key and are shared across organizations, while membership is independent in each organization. Creating an existing Email through SCIM for an organization only adds that account to the organization; deactivation also affects only that organization. Display names are account-level, so a SCIM name change appears in every organization.