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. When you add someone to an Okta Group, they appear in Agent Handler. When you remove them, their access ends - no manual cleanup, 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. It sits on top of SSO, which authenticates members while SCIM provisions them. Turn on SSO first, then layer SCIM on top.

Setting up SCIM

  1. Open the Provisioning tab.
  2. Click Enable SCIM. Agent Handler generates a SCIM token and a base URL.
  3. Copy both - you’ll paste them into your IdP next.
  4. In your IdP, add Agent Handler as a SCIM target with these credentials. The setup wording differs by IdP; the values are always the same:
    • SCIM base URL: the URL Agent Handler showed you, of the form https://ah-api.merge.dev/scim/v2/.
    • Bearer token: the SCIM token Agent Handler generated.
    • Provisioning method: push (Okta), automatic (Azure AD).
  5. Configure attribute mappings in your IdP - see per-IdP notes below.
  6. Provision a test user from your IdP. Within a minute or two, they should appear in Settings → Members.

Test thoroughly before turning on enforcement. SCIM misconfigurations can lock out your whole team if you flip “require SSO + SCIM” prematurely.

Per-IdP setup

  1. Okta Admin Console → your Agent Handler SSO application → Provisioning → Configure API Integration.
  2. Check Enable API integration.
  3. Base URL: paste from Agent Handler.
  4. API token: paste the SCIM token.
  5. Click Test API Credentials - Okta verifies the connection.
  6. Save.
  7. Under Provisioning → To App, enable Create Users, Update User Attributes, and Deactivate Users.
  8. Map attributes - email, given name, family name at minimum.
  9. Assign Okta Groups to the application; their members get pushed into Agent Handler.
  10. Push Groups: Provisioning → Push Groups, select the Groups you want synced.

Mapping IdP Groups to roles and tools

Once Groups sync in, you assign each one a dashboard role and tool access from Manage access → Group access, and set a baseline for everyone under Default access. Users in multiple Groups get the highest dashboard role and the most permissive tool access across them. See Managing tool access for the full model.

Deprovisioning

The contract: when a user is removed from your IdP (or removed from the Agent Handler-bound Group in your IdP), Agent Handler:

  1. Marks the dashboard user as deactivated. They can no longer log in.
  2. Deactivates the linked Registered User. All their stored credentials are revoked. Active OAuth tokens for the MCP URL are invalidated.
  3. Records the deprovisioning event in the Audit Trail.

Audit log entries and tool-call history for the deprovisioned user are retained per your org’s retention policy (default 90 days).

Token rotation

The SCIM token has the same security profile as an API key - anyone with it can create and modify users in your org. Rotate yearly or on any suspicion of leak.

To rotate: in the Provisioning tab, click Regenerate token. The new token is shown once. Update your IdP’s stored copy before the next sync runs, or the next sync will fail and provisioning will pause.

Common issues

  • Sync runs but no users appear. Check the IdP’s sync log for error responses from Agent Handler. Most often it’s an attribute mapping issue - the IdP is sending fields Agent Handler doesn’t recognize, or omitting required fields.
  • Users appear but with the wrong role. Group mappings are set but the user isn’t in the Group, or the IdP isn’t pushing the Group. Confirm Group push is enabled.
  • Deprovisioning lags. Each IdP runs its own sync schedule. Okta is near-real-time on user removal; Azure runs every ~40 minutes. The Audit Trail records the deprovisioning event whenever it fires.

Next

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