Administer

SCIM provisioning

Auto-provision and deprovision dashboard members and Groups from your IdP.

SCIM (System for Cross-domain Identity Management) lets your IdP push user and Group changes into Agent Handler automatically. Add someone to an Okta Group and they appear in Agent Handler. Remove them and their access ends, with no manual cleanup and no orphaned accounts.

SCIM is part of the Agent Handler for Employees setup, and it’s how Registered Users get created: your IdP provisions each employee once, and they get both a dashboard user and a Registered User.

Before you start: turn on SSO first. SSO signs members in, and SCIM provisions them. SCIM also needs a payment method, so add one under Settings → Billing. The card alone doesn’t change your plan, but your first synced employee does: see Provisioning employees changes your plan.

Set up SCIM

1

Get your SCIM token and base URL

Open the Provisioning tab and click Enable SCIM. Agent Handler shows a SCIM token and a base URL of the form https://ah-api.merge.dev/scim/v2/. Copy both. The token is shown once.

2

Connect your IdP

The wording differs by IdP. The values are always the same.

  1. Okta Admin Console → your Agent Handler SSO application → Provisioning → Configure API Integration.
  2. Check Enable API integration, paste the base URL and the SCIM token as the API token.
  3. Click Test API Credentials, then Save.
  4. Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.
  5. Map attributes: email, given name, and family name at minimum.
  6. Assign the Groups you want to provision, and select them under Provisioning → Push Groups.
3

Set up an Admin Group

Dashboard roles come from Group mappings, so your Admins need a Group that gives them Admin. Do these in order:

  1. In your IdP, create a Group named Merge Admins. Leave it empty.
  2. Assign and push it like your other Groups.
  3. In Agent Handler, go to Manage access → Group access and set Merge Admins to the Admin role.
  4. Add your Admins to Merge Admins in your IdP.

Map the Group before you add people. Someone who syncs into an unmapped Group gets the default role, so an Admin can lose Admin on the next sync.

4

Test with one user

Provision one test user from your IdP. Within a minute or two, they appear in Settings → Members with the role their Group gives them. Test before you require SSO and SCIM for everyone.

Roles and tools

Each synced Group gets a dashboard role and tool access under Manage access → Group access. Default access sets the baseline for everyone. A user in several Groups gets the highest role and the most permissive tool access across them. See Managing tool access for the full model.

Group mappings apply on every sync, not only the first. A user whose Groups give no role gets the default role.

A sync or a mapping change never removes the last Admin, so your organization can’t be locked out

Deprovisioning

When a user is removed from your IdP, or from the Group that grants them Agent Handler, Agent Handler:

  1. Deactivates the dashboard user. They can no longer sign in.
  2. Deactivates the linked Registered User, revokes their stored credentials, and invalidates their OAuth tokens for the MCP URL.
  3. Records the event in the Audit Trail.

Audit log entries and tool-call history for the user are kept for your organization’s data retention window, then purged.

Token rotation

Anyone with the SCIM token can create and modify users in your organization, so treat it like an API key. Rotate it yearly, or right away if you think it leaked.

In the Provisioning tab, click Regenerate token. The new token is shown once. Update your IdP before its next sync, or that sync fails and provisioning pauses.

Common issues

Check your IdP’s sync log for errors from Agent Handler. It’s usually attribute mapping: the IdP sends fields Agent Handler doesn’t recognize, or leaves out required ones.

The user isn’t in the Group you mapped, or your IdP isn’t pushing that Group. Confirm Group push is on.

None of their Groups is mapped to Admin, so the sync gave them the default role. Map their Group to Admin under Manage access → Group access, then sync again.

Each IdP syncs on its own schedule. Okta removes users in near real time. Azure syncs about every 40 minutes. The Audit Trail records the event when it happens.

Next

Add a second factor on every dashboard sign-in with Multi-factor authentication.