SCIM User Provisioning – Assembled
Use SCIM (System for Cross-domain Identity Management) to automatically create, update, and deactivate Assembled user accounts from your identity provider (IdP), such as Okta, Microsoft Entra ID (Azure AD), or OneLogin.
Assembled uses WorkOS Directory Sync as the SCIM intermediary. Your IdP sends SCIM updates to WorkOS; Assembled polls WorkOS and applies changes to your account. You do not configure a SCIM endpoint URL that points directly at Assembled.
What SCIM provisioning does
When configured, directory sync keeps Assembled user accounts aligned with your IdP:
| IdP action | Assembled behavior |
|---|---|
| User assigned to the app | Creates a new Assembled user, or updates an existing active user with the same email |
| User profile updated | Updates the user's email, first name, last name, and/or role (when applicable) |
| User added to / removed from a group | Updates the user's Assembled role, if a group → role mapping is configured |
| User removed or deprovisioned | Deactivates the Assembled user (same outcome as deactivating a user in the Assembled UI) |
SCIM provisioning manages Assembled login accounts and role assignment. It does not:
- Create or update agent profiles (sites, queues, teams, channels, schedules, and so on)
- Send Assembled invitation emails to newly provisioned users
- Map custom SCIM attributes beyond the fields listed in this article
If you need agents in Assembled, create or manage agent profiles separately after users are provisioned.
Prerequisites
Before you can set up SCIM provisioning:
- Assembled admin access — you must have at least Admin permissions.
- SCIM enabled for your company — SCIM provisioning must be turned on for your account. Contact your Assembled account team or support if you don't see SCIM provisioning under Configure.
- An IdP that supports SCIM 2.0 — Okta, Microsoft Entra ID, OneLogin, and other providers supported by WorkOS Directory Sync.
Set up SCIM provisioning
Step 1: Enable SCIM in Assembled
- In Assembled, go to Configure → SCIM provisioning (
/settings/scim-provisioning). - Click Enable SCIM provisioning.
This creates a WorkOS organization for your company, syncs your Assembled roles into WorkOS, and prepares background sync jobs. Status changes to Setting up.
Step 2: Connect your IdP in the WorkOS portal
- On the SCIM provisioning page:
- If status is Setting up, click Set up integration.
- If status is Active, click Manage SCIM configuration.
- You'll be redirected to the WorkOS Admin Portal.
- In the portal, connect your IdP and complete SCIM configuration using WorkOS's instructions for your provider.
IdP-specific connector steps (Okta, Entra ID, OneLogin, and others) are documented by WorkOS. See WorkOS Directory Sync documentation for provider-specific setup.
Step 3: Set up group → role mapping (optional, but recommended)
To automatically assign roles based on IdP group membership, you need a group → role mapping configured. This determines which Assembled role a user receives based on the groups they belong to in your IdP.
To set up or update your mapping: Contact Assembled support. The Assembled team configures the mapping on your behalf. Self-service mapping configuration isn't available today.
When requesting setup, include:
- The IdP group names you want to map
- The Assembled role each group should correspond to
Without a mapping configured, all SCIM-provisioned users default to the Basic role. You can update users' roles manually in Assembled, but those changes may be overwritten if a mapping is later configured.
Step 4: Confirm sync is active
Return to Configure → SCIM provisioning in Assembled.
| Status | Meaning |
|---|---|
| Not configured | SCIM has not been enabled |
| Setting up | SCIM is enabled, but no directory sync has completed successfully yet |
| Active | At least one sync cycle completed successfully |
When status is Active, the page shows when the last successful sync ran. If a sync error occurs, an error message appears with details.
Synced user attributes
Assembled applies the following fields from directory sync:
| Attribute | Synced on create | Synced on update | Notes |
|---|---|---|---|
| Yes | Yes | Primary identifier. When a user's email changes in your IdP, Assembled uses the previous email from the sync event to find and update the correct account. | |
| First name | Yes | Yes | Updated only when the value changes. |
| Last name | Yes | Yes | Updated only when the value changes. |
| Role | Yes | Yes | Driven by group → role mapping. See Role assignment below. |
| Group membership | Yes | Yes | Used to determine the user's Assembled role via the configured group → role mapping. Groups are not stored in Assembled as a separate concept. |
The following are not synced: agent profile fields, custom SCIM attributes, and general "suspended" state from the IdP (deactivation in Assembled happens only when the user is removed or deprovisioned via SCIM).
Role assignment
Assembled assigns roles to SCIM-provisioned users based on a group → role mapping configured in WorkOS by the Assembled team.
How it works:
- Your IdP sends each user's group membership to WorkOS as part of directory sync.
- Assembled applies the configured mapping to determine which Assembled role each user should have.
- When a user is added to or removed from a group in your IdP, their Assembled role updates automatically based on the mapping.
Default behavior:
- If a mapping is configured and the user belongs to a mapped group → they receive the corresponding Assembled role.
- If a mapping is not configured, or the user doesn't belong to any mapped group → they receive the Basic role.
To change your group → role mapping, contact Assembled support with the updated mapping you'd like in place.
Deprovisioning users
When a user is removed from the SCIM application in your IdP (or otherwise deprovisioned via directory sync), Assembled deactivates the user account. This matches deactivating a user manually in the Assembled UI.
Deprovisioning does not:
- Permanently delete the user record
- Delete associated agent data
- Remove historical schedules or metrics
If the deactivated user has an associated agent profile, Assembled sets the agent's end date to the deactivation time (or keeps an earlier end date if one was already set).
Re-provisioning a previously deactivated user
If a user was deactivated via SCIM and later re-added in your IdP, Assembled provisions them as a new user account rather than reactivating the previous one. Plan accordingly if you need continuity with an earlier account (for example, linked agent history or permissions).
How sync works
- Assembled runs a background sync service that polls the WorkOS Events API for directory sync events.
- Events are processed in order. The sync advances only after all events in a batch are processed successfully.
- If processing fails, the sync job reports an error on the SCIM provisioning page and retries on the next sync cycle.
- Changes from your IdP are not instantaneous; they typically appear within a few minutes depending on sync scheduling.
Troubleshooting
SCIM provisioning page is missing
- Confirm you have Admin permissions.
- Confirm SCIM provisioning is enabled for your company. Contact Assembled support if the page is not visible.
Status stuck on "Setting up"
- Complete IdP configuration in the WorkOS Admin Portal ( Set up integration).
- Ensure at least one user is assigned to the Assembled application in your IdP so sync events are generated.
- Check for sync errors on the SCIM provisioning page.
Sync error displayed
- Review the error details on the SCIM provisioning page.
- Verify your IdP connection in the WorkOS portal ( Manage SCIM configuration).
- Contact Assembled support with the error message and approximate time of the failure.
User created in IdP but not appearing in Assembled
- Confirm SCIM status is Active and the last sync time is recent.
- Verify the user is assigned to the Assembled application in your IdP.
- Check whether a deactivated account already exists for that email.
User assigned to the wrong role (or stuck on Basic)
- Confirm a group → role mapping has been configured for your account. Without one, all users default to Basic.
- Verify the user is in the expected IdP group.
- If the mapping is set up but the user's role isn't updating, allow a few minutes for the next sync cycle.
- To update the mapping itself, contact Assembled support.
User deactivated in IdP but still active in Assembled
- Confirm the user was removed from the application or deprovisioned in your IdP (not only suspended in a way that does not emit a delete event).
- Check for sync errors and wait for the next sync cycle.
Limitations summary
| Supported | Not supported |
|---|---|
| User create, update, and deactivate | Agent profile creation or updates |
| Email, first name, last name, and role sync | Custom SCIM attribute mapping |
| Group → role mapping (configured by Assembled support) | Self-service group → role mapping configuration |
| Automatic role updates when group membership changes | Direct SCIM endpoint to Assembled |
| IdP setup via WorkOS Admin Portal | Hard delete of users or agents |
| Deactivation with agent data preserved | Automatic invitation emails |
Getting help
For setup assistance, group → role mapping configuration, or to enable SCIM provisioning for your account, contact your Assembled account team or support.
For IdP connector configuration in WorkOS, see WorkOS Directory Sync documentation.