SCIM provisioning
System for Cross-domain Identity Management (SCIM) lets you automatically provision users and groups into Mistral from an identity provider, such as Microsoft Entra ID. Use it to manage onboarding, group membership, and offboarding from your identity provider.
Manage group membership in your identity provider and configure the group's permissions in Mistral. See Manage groups and roles for permission and Workspace assignments.
Private preview
SCIM provisioning is available in private preview.
Deactivation affects every Organization
Deactivating a SCIM-managed user signs them out of every Mistral Organization they belong to and deletes their API keys. Their memberships are kept, and reactivating them restores their access, but not their API keys. Review the user lifecycle before enabling deprovisioning in your identity provider.
Before you start
Before you enable SCIM:
- Claim and verify the email domains of the users you intend to provision.
- Configure a SAML SSO connection.
- Require SSO sign-in for each verified domain you intend to provision users from, on Admin > Access.
All SCIM-provisioned users must sign in through your configured SSO provider. If a user already exists but SSO is not enforced for their domain, provisioning fails with 409 Conflict ("identity already exists in another scope"). Enforce SSO for their domain first.
Decide whether your identity provider will manage users only or users and groups. If you use groups, plan their membership and the permissions each group should grant. Prepare your identity provider's provisioning configuration and assign the users who need access before switching Mistral to SCIM.
Enable SCIM
- Open Admin Panel›Administration›Access ↗.
- Under Provisioning, select SCIM as the provisioning method.
- Copy and securely store the generated bearer token before closing the dialog. It is shown only once.
- Copy the SCIM URL and use it with the bearer token to configure provisioning in your identity provider.
- Start provisioning in your identity provider and send a test user. For provider-specific steps, see Set up SCIM with Microsoft Entra ID.
- Check the user on Admin > Members. SCIM-managed users show the Externally managed badge. Changes are asynchronous and may not appear immediately.
Provision users before their first SSO sign-in
Enabling SCIM stops new users from joining your Organization automatically through SSO. They must be provisioned through SCIM first. Existing members keep their access and role. To avoid locking out new users, have your identity provider configuration ready and start provisioning as soon as you enable SCIM.
If the bearer token is lost or exposed, select Rotate next to SCIM bearer token on the Access page. The previous token stops working immediately. Update the token in your identity provider before it sends more requests.
Choose what SCIM manages
- Users only: use SCIM for provisioning and deprovisioning. Manage any group memberships in Mistral or through the Admin API.
- Users and groups: sync users, groups, and their memberships from your identity provider. Configure the permissions and Workspace access that those groups grant in Mistral.
Newly provisioned users join with the member role and access to your Organization's default Workspace. If automatic seat assignment is enabled, they also receive a seat while seats remain. Provisioning never buys extra seats.
Map SCIM attributes
User attributes
| Attribute | How Mistral uses it |
|---|---|
userName | Required, unique login identifier. Must be an email address. |
active | Send true for enabled users and false for disabled users. Setting a user to false deactivates them; a new user sent with false joins your Organization deactivated. A new user sent without active is treated as active; an update without active leaves their status unchanged. |
emails | Optional list of email addresses with a value and optional primary flag. The first entry with primary: true becomes the user's display email. Other addresses are stored but not used. If none is primary, Mistral uses userName. The email's type does not affect this selection. |
name.givenName | Displayed as the user's first name. |
name.familyName | Displayed as the user's last name. |
For example, a core SCIM User payload can look like this:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "ada@example.com",
"active": true,
"emails": [{ "value": "ada@example.com", "primary": true }],
"name": { "givenName": "Ada", "familyName": "Lovelace" }
}Group attributes
| Attribute | How Mistral uses it |
|---|---|
displayName | Required group name. Filterable. |
externalId | Optional identifier set by the SCIM client. Must be unique within the Organization if set. Filterable. |
members | List of members. Each member's value is a user's SCIM identity ID, display is read-only, and type is "User". |
Supported schemas and additional fields
The SCIM API supports:
urn:ietf:params:scim:schemas:core:2.0:Userurn:ietf:params:scim:schemas:core:2.0:Groupurn:ietf:params:scim:schemas:extension:enterprise:2.0:User
Only a subset of schema fields is used within Mistral. In addition to the mappings above:
| Schema | Attribute | Type | Behavior |
|---|---|---|---|
| User | id | UUID | Read-only identity ID. |
| User | externalId | String | Optional and filterable. Stored but not used within Mistral. |
| User | groups | Array | Read-only group memberships, with value, display, and type. Change membership through the Group resource's members attribute. |
| Group | id | UUID | Read-only group ID. |
| Enterprise User extension | employeeNumber | String | Optional and filterable. Stored but not used within Mistral. |
How synchronization works
Mistral maintains a SCIM directory for your Organization. Your identity provider pushes changes to this directory through the SCIM URL and can read from it. Mistral never fetches changes from your identity provider.
Changes reach your Organization in two asynchronous steps:
- Your identity provider sends changes to Mistral's SCIM directory on its own schedule.
- Mistral applies those changes to your Organization automatically.
Users do not need to sign in for changes to apply. Check the affected user or group in Mistral to confirm the result.
When group memberships change, the affected users gain or lose the Workspaces and permissions granted by those groups. Deleting a SCIM-managed group removes the access it granted; access granted directly or through other groups remains.
A group in Mistral only shows members who are provisioned. Users who have not been provisioned yet are left out until they are. Deactivated users keep their group memberships.
Run a manual sync
A manual sync compares your Organization with Mistral's SCIM directory and reconciles any drift. It does not fetch new changes from your identity provider. If a change has not reached the SCIM directory, a manual sync cannot apply it.
You should not need to run a manual sync often. Use it when a change your identity provider sent successfully is still missing after some time, or if Mistral support asks you to.
Large directories can take longer to sync. Automatic changes continue while a manual sync runs, so its Preview or results may be out of date by the time it finishes.
You need the Organization admin role. Only one manual sync can run at a time.
- On Admin > Access, select Run manual sync under Provisioning.
- Choose Preview. It lists everything a sync with every option selected would change, without changing anything.
- When the run finishes, select View results and review the proposed changes.
- If the changes are expected, run another manual sync with Apply and select the categories to reconcile.
Apply re-checks the SCIM directory when it runs, so its changes can differ from your last Preview. A manual sync never deletes users. Users it deactivates are reactivated when your identity provider sets them to active: true. It does not compare user names or email addresses.
Wait for existing members to be provisioned
If you enabled SCIM in an Organization with existing SSO members, wait until your identity provider has finished provisioning everyone before applying Deactivate users who are inactive in, or missing from, the SCIM directory. Otherwise, members who joined through SSO but are missing from the SCIM directory can be deactivated.
Manual sync options
| Option | What Apply does |
|---|---|
| Sync users | Adds active SCIM directory users who are missing from the Organization, with the member role and default Workspace access, and reactivates active directory users who are deactivated in Mistral. Also select Sync group memberships to restore SCIM group memberships. |
| Deactivate users who are inactive in, or missing from, the SCIM directory | Deactivates inactive users and externally managed members who are missing from the directory but present in your Organization, including members who joined through SSO before SCIM was enabled. Deactivated users lose access to every Mistral Organization and their API keys are deleted. Requires Sync users. |
| Sync groups | Creates missing SCIM-managed groups and renames groups whose names changed. |
| Sync group memberships | Adds and removes SCIM-managed group members to match the directory. Members added manually or through the API in Mistral are removed. Requires Sync groups. |
| Delete groups that aren't in the SCIM directory | Deletes SCIM-managed groups missing from the directory. Groups created manually or through the API in Mistral are never deleted. Requires Sync groups. |
Review sync results
Last manual sync shows the most recent run. Manual sync history lists every run, who started it, whether it was a Preview or Apply, and its status. Select View results to see a detailed breakdown of which users, groups, and group memberships the sync would apply to for a Preview, or applied to for an Apply: users added or deactivated, groups added or deleted, and membership changes by group.
| Status | Meaning |
|---|---|
| Pending / Running | The run is queued or in progress. |
| Success | Every change was applied. For Preview, the results were computed and nothing changed. |
| Failed | At least one change failed. Other changes may have been applied; review the results before retrying. |
| Skipped | The Organization was not eligible, for example because SCIM is no longer enabled. |
Starting a manual sync and the changes it makes are recorded in your audit log. You can also start a sync through POST /v1/admin/scim/sync; see the SCIM sync API reference.
Understand the user lifecycle
Deactivation, reactivation, and deletion are different actions. Check your identity provider's documentation to understand what it sends.
| Typical action in your identity provider | SCIM request | Result in Mistral |
|---|---|---|
| Disable a user or remove them from the Mistral app | active: false | Deactivate the user. |
| Enable a user again or reassign them | active: true | Reactivate the user. |
| Permanently delete a user, with some providers | DELETE | Permanently delete the user's account. |
Deactivate a user
Setting an existing user to active: false deactivates their Mistral account, in every Mistral Organization they belong to, not only yours:
- Ends all their sessions and prevents them from signing in.
- Deletes every API key they own. Automations and scheduled tasks that use those keys stop working.
- Releases their seats.
- Deletes an Organization's own API keys once it has no active member left.
Their Organization roles, Workspace memberships and roles, and group memberships are kept. SCIM group changes still apply while they are deactivated.
The account and identity are not deleted. Your audit log records the deactivation as user.deactivate. Mistral does not notify the user; use your usual offboarding process. Content they created, such as conversations, files, and agents, stays in place and is not transferred to another user.
Reactivate a user
Setting a deactivated user to active: true reactivates them in every Organization they belong to:
- They can sign in again, with the Organization roles, Workspaces, and groups they had.
- Each seat they held is given back while the Organization has a free one.
API keys are not restored. The user creates new ones and updates the automations that used the old keys. Your audit log records the reactivation as user.reactivate.
Delete a user
A SCIM DELETE removes the user from every Organization, then permanently deletes their identity and Mistral account. If you provision the same person again, they receive a new, empty account. The removal is recorded in audit logs with reason scim.
Group management FAQ
Will SCIM-created groups overwrite existing groups?
No. SCIM-managed groups are distinct from groups created in Mistral, even if their names match. Look for the Externally managed badge in the UI or the boolean externally_managed field in Admin API responses.
Can I add a SCIM-managed user to a group managed in Mistral?
Yes, but SCIM does not manage that membership. Review the permissions the group grants and manage its membership in Mistral.
Can I add a non-SCIM-managed user to a SCIM-managed group?
Not from the Mistral UI. Provision the user through SCIM first, then add them to the group in your identity provider. If members are added through another method, such as the API, the next manual sync with Sync group memberships removes them.
Disable SCIM
On Admin > Access, change the provisioning method to another mode. Mistral removes the SCIM connection and no longer accepts changes from your identity provider. Turn off provisioning in your identity provider too.
Existing users, groups, and memberships stay as they are and stop updating automatically. New users join according to the provisioning mode you select. The change is recorded in your audit log.
Known limitations
- A user can only be SCIM-provisioned into the Mistral Organization which configured SSO for their domain. Moving them to another SCIM Organization requires deleting the user through SCIM first. This permanently deletes their account; contact support if you need help planning the move.
- While SCIM is enabled, a domain configured for SSO cannot be removed from the SSO configuration. SCIM requires SSO-enforced sign-in. Contact support if you need to change this configuration.
GET /Userssupports only theeqfilter operator, withuserName,externalId,employeeNumber, orgroups.value.GET /Groupssupports onlyeq, withdisplayNameorexternalId. Operators such asne,co,sw, andeware not supported for users or groups.GET /Groupsomits group members. UseGET /Groups/{id}to retrieve an individual group's membership.- Users and groups support offset pagination with
startIndexandcount. The maximumstartIndexis5000, and the maximumcountis1000. - Users and groups also support cursor pagination with
countandcursor. Responses includenextCursorunless there is no next page. Cursors expire after one hour. Cursor pagination has no upper bound on the result set.
Troubleshooting
A change is not reflected in Mistral
Changes are asynchronous. If a change is still missing after some time:
- Check your identity provider's provisioning logs. If the request failed or was not sent, fix the cause there, such as an unassigned user or a user outside the provisioning scope.
- Run a manual sync with Preview and select View results.
- If the change is listed, it reached Mistral's SCIM directory but has not been applied to your Organization. Run Apply to reconcile it now.
- If it is not listed, check your identity provider again. If its logs show success, contact support.
Manual sync does not compare names or email addresses. If those changes are missing despite a successful provisioning request, contact support.
Do not apply unexpected deactivations. Existing SSO members may be missing from the SCIM directory because your identity provider has not provisioned them yet.
409 Conflict: identity already exists in another scope
Check these two possible causes:
- SSO is not enforced for the user's domain. On Admin > Access, require SAML SSO for their verified email domain, then retry provisioning.
- The user was SCIM-provisioned into another Mistral Organization. Identify the Organization that provisioned them. Contact support before moving them, or review the permanent deletion consequences before deleting them through SCIM in the original Organization and provisioning them in the new one.