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:

1. **Assembled admin access** — you must have at least Admin permissions.
2. **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.
3. **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

1. In Assembled, go to **Configure → SCIM provisioning** (`/settings/scim-provisioning`).
2. 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

1. On the SCIM provisioning page:
   - If status is **Setting up**, click **Set up integration**.
   - If status is **Active**, click **Manage SCIM configuration**.
2. You'll be redirected to the **WorkOS Admin Portal**.
3. 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](https://workos.com/docs/directory-sync) 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                                                                                                                                                        |
|---------------------|------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Email**           | 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](https://support.assembled.com/hc/en-us/articles/45775797385613-SCIM-User-Provisioning#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:**

1. Your IdP sends each user's group membership to WorkOS as part of directory sync.
2. Assembled applies the configured mapping to determine which Assembled role each user should have.
3. 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](https://workos.com/docs/directory-sync).