Provisioning

SCIM provisioning

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

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, 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.

  1. Open Provisioning → 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

  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.

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.

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 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 existing 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.

Audit entries and tool call history for the deprovisioned employee are kept for your organization’s 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.