> This page is for Workforce. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # SCIM provisioning > How SCIM works in Workforce: setup per IdP, what a synced Group carries, deprovisioning, and token rotation. SCIM (System for Cross-domain Identity Management) lets your IdP push user and Group changes into Workforce automatically. Add someone to an Okta Group and they appear as an employee. Remove them and their access ends, with no manual cleanup and no orphaned accounts. SCIM is how employees get created: your IdP provisions each person once, and they arrive with the Groups they belong to and a Gateway API key minted per Group. It sits on top of [SSO](/merge-workforce/provisioning/sso), which authenticates people while SCIM provisions them. Turn on SSO first, then layer SCIM on top. ## Setting up SCIM SCIM needs a payment method on the organization. On a free plan the dashboard asks for a card before it will generate the SCIM token, so add one first. Adding the card does not by itself move you to another plan, and neither does your first synced employee if you are a Workforce organization: see [Provisioning employees and your plan](/merge-workforce/settings/billing#provisioning-employees-and-your-plan). 1. Open [Provisioning → Sync](https://wf-develop.merge.dev/groups/sync). 2. Pick your provider. Okta, Microsoft Entra ID, OneLogin, and JumpCloud each get their own step-by-step checklist; anything else gets the generic SCIM 2.0 one. 3. Generate the SCIM token from the checklist. The raw value is shown once, in the response that creates it, so copy it before you navigate away. 4. In your IdP, add Merge as a SCIM target. The setup wording differs by IdP; the values are always the same: * **SCIM base URL:** the URL the checklist shows, of the form `https://ah-api.merge.dev/scim/v2` * **Bearer token:** the SCIM token you generated * **Provisioning method:** push (Okta), automatic (Azure AD) 5. Configure attribute mappings in your IdP. See the per-IdP notes below. 6. Provision a test user. Within a minute or two they appear in the **Synced from directory** panel next to the checklist, which reports users imported and the member count of each Group as they land. Test thoroughly before turning on enforcement. A SCIM misconfiguration can lock out your whole team if you require SSO and SCIM prematurely. ## Per-IdP setup #### Okta 1. Okta Admin Console → **Applications → Applications → Browse App Catalog**. 2. Search for **SCIM 2.0 Test App (Header Auth)** and click **Add Integration**. Name it, click **Next**, then **Done**. 3. On the **Provisioning** tab, click **Configure API Integration** and check **Enable API integration**. 4. Base URL: paste from the checklist. API token: paste the SCIM token. 5. Click **Test API Credentials**, then **Save**. 6. Under **Provisioning → To App**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. 7. Map attributes: email, given name, family name at minimum. 8. In Okta, create a Group named **Merge Admins** and leave it empty for now. 9. On the **Assignments** tab, assign the Groups you want to provision, **Merge Admins** included. 10. On the **Push Groups** tab, select every Group you want synced, **Merge Admins** included. 11. Map **Merge Admins** to the **Admin** dashboard role under **Group access**. 12. Now add your admins to **Merge Admins** in Okta. Every sync restores them to Admin, so a resync can never lock an admin out. > **Warning** > > Steps 8 to 12 have to happen in that order. A user who syncs before their Group is mapped to a role falls back to the default role, so an admin whose Group is populated first loses dashboard access on the next resync. Map the Group, then populate it. #### Azure AD / Entra ID 1. Azure portal → **Enterprise applications → your Merge app → Provisioning**. 2. Set provisioning mode to **Automatic**. 3. Tenant URL: paste the SCIM base URL. Secret token: paste the SCIM token. 4. Click **Test Connection**, then save. 5. Under **Mappings**, configure user and Group attribute mappings: email, displayName, given name, family name. 6. Create a security Group named **Merge Admins** and leave it empty. Assign it to the application with your other security Groups. 7. Toggle **Provisioning Status** to On. Azure runs the first sync within about 40 minutes, which is configurable but not faster. 8. In Workforce, map **Merge Admins** to the **Admin** role under **Group access**. 9. Now add your admins to **Merge Admins** in Entra. #### Other SCIM-capable IdPs Any SCIM 2.0-compliant IdP works. You need: * SCIM base URL * SCIM bearer token * The ability to push users and Groups, not only users Common attribute mappings: `userName` to `email`, `name.givenName` to `firstName`, `name.familyName` to `lastName`. Each IdP names these slightly differently; the SCIM 2.0 spec is the canonical reference. Create a Group named **Merge Admins** and leave it empty. Push it with your other Groups, map it to the **Admin** role under **Group access**, then add your admins to it. ## What a synced Group carries Once Groups sync in, each one carries the access its members get: Connectors and Tool Packs, a routing policy, an approved-models list, a budget, and a dashboard role. Set the organization-wide baseline under **Default access** on the same Sync tab, then configure each Group from its own detail page. Employees in more than one Group get the most permissive tool access across them and the highest dashboard role. [Groups and access](/merge-workforce/provisioning/groups) is the full model. Map a Group to its dashboard role before you put anyone in it. A user who syncs while their Group has no mapping takes the default role, and that applies on every resync rather than only the first, so an unmapped Group can demote an admin. A sync or a mapping change never removes the last Admin. ## Deprovisioning When someone is removed from your IdP, or from the Group bound to Merge: 1. Their dashboard user is deactivated. They can no longer sign in. 2. Their employee record is deactivated, which stops their OAuth tokens for the MCP endpoint from being accepted. The deactivation is a soft delete, so their history stays readable. 3. The event is recorded in the [Audit trail](/merge-workforce/logs/audit-trail). The last active Admin is the exception. Merge refuses to deactivate them, and your IdP logs the error. Make someone else Admin first. Audit entries and tool call history for the deprovisioned employee are kept for your organization's [data retention](/merge-workforce/logs/audit-trail#data-retention) window, then purged. ## Token rotation The SCIM token has the same security profile as an API key: anyone holding it can create and modify users in your organization. Rotate yearly, and immediately on any suspicion of a leak. Generate a replacement from the Sync tab. The new value is shown once. Update your IdP's stored copy before the next sync runs, or that sync fails and provisioning pauses. ## Common issues * **Sync runs but no users appear.** Check the IdP's sync log for error responses. Most often it is an attribute mapping issue: the IdP is sending fields that are not recognized, or omitting required ones * **Users appear with the wrong role.** Group mappings are set but the user is not in the Group, or the IdP is not pushing the Group. Confirm Group push is enabled * **An admin loses Admin after a resync.** Their Group has no role mapping, so the resync applied the default role. Map the Group under **Group access**, then have them sync again. Mapping the Group before it is populated avoids this. * **Deprovisioning lags.** Each IdP runs its own sync schedule. Okta is near-real-time on user removal; Azure runs roughly every 40 minutes. The Audit trail records the event whenever it fires ## Next See how default, Group, and per-employee access resolve into what one person can reach in [Groups and access](/merge-workforce/provisioning/groups).