Skip to navigation
AdministerProvisioning

SCIM provisioning

Auto-provision and deprovision employees and Groups from your identity provider

SCIM lets your identity provider (IdP) push users and Groups into Workforce. Each synced employee gets the access of their Groups. Removing them in your IdP ends their access.

Turn on SSO first, then set up SCIM.

Set up SCIM

  1. Open Provisioning → Sync and pick your provider (Okta, Microsoft Entra ID, OneLogin, JumpCloud, or generic SCIM 2.0).

  2. Generate the SCIM token. It is shown once.

  3. In your IdP, add Merge as a SCIM target:

    FieldValue
    SCIM base URLThe URL the checklist shows, of the form https://wf-api.merge.dev/scim/v2
    Bearer tokenThe SCIM token
    Provisioning methodPush (Okta), automatic (Azure AD)

  4. Configure attribute mappings. See Per-IdP setup.

  5. Provision a test user. It appears in the Synced from directory panel within a minute or two.

Test SCIM before you require SSO and SCIM. A misconfiguration can lock out your whole team.

Per-IdP setup

Map a Group to its dashboard role before adding anyone to it. A user whose Group has no role mapping gets the default role on every resync, which can demote an admin. Each setup below creates an empty Merge Admins Group, maps it to Admin, then adds admins.

  1. Applications → Applications → Browse App Catalog, add SCIM 2.0 Test App (Header Auth).
  2. Provisioning → Configure API Integration, check Enable API integration.
  3. Base URL: from the checklist. API token: the SCIM token. Click Test API Credentials, then Save.
  4. Provisioning → To App: enable Create Users, Update User Attributes, and Deactivate Users.
  5. Map email, given name, and family name at minimum.
  6. Create an empty Group named Merge Admins.
  7. On Assignments and Push Groups, add every Group to sync, Merge Admins included.
  8. In Workforce, map Merge Admins to Admin under Group access.
  9. Add your admins to Merge Admins in Okta.

Each synced Group carries Connectors, Tool Packs, a routing policy, approved models, a budget, and a dashboard role. See Groups and access.

Deprovisioning

When someone is removed from your IdP, or from the Group bound to Merge:

  1. Their dashboard user is deactivated.
  2. Their employee record is soft-deleted and their MCP OAuth tokens stop working.
  3. The event is recorded in the Audit trail.

Merge refuses to deactivate the last active Admin. History is kept for your data retention window.

Rotate the SCIM token

Rotate yearly, and immediately if leaked. Generate a replacement on the Sync tab and update your IdP before the next sync, or provisioning pauses.

Common issues

SymptomFix
No users appearCheck the IdP sync log. Usually an attribute mapping error
Wrong roleConfirm the user is in the Group and Group push is enabled
Admin loses Admin after resyncMap their Group under Group access and resync
Deprovisioning lagsOkta is near real time; Azure runs roughly every 40 minutes