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 sits on top of SSO. SSO authenticates members; SCIM provisions them. Most teams turn on SSO first, then layer SCIM on once the dashboard sees regular use.

For the Context layer for employees setup, SCIM is also how Registered Users get created - your IdP provisions employees once, and each one gets both a dashboard user and a Registered User behind the scenes.

What SCIM does that SSO doesn’t

SSO answers “is this person allowed to log in?” SCIM answers “should this person exist at all, and what should they have access to?” In practice:

  • Provisioning. Your IdP creates members in Agent Handler when they’re added to the right Group, instead of you inviting each one manually.
  • Deprovisioning. Removing a member from your IdP propagates to Agent Handler within minutes - no manual cleanup, no orphaned access.
  • Group sync. IdP Groups are pushed into Agent Handler, where you can map them to roles or Tool Packs.
  • Attribute sync. Email, name, department, custom attributes - kept current as the user’s IdP profile changes.

SSO alone covers login. SCIM is where security teams draw the line for automated deprovisioning.

Setting up SCIM

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

By default, every SCIM-provisioned user gets a default role you set in Settings → Provisioning. For finer control, map specific IdP Groups to specific Agent Handler roles.

  1. Open Settings → Provisioning → Group mappings.
  2. For each IdP Group you’ve pushed, pick the Agent Handler role it should grant: Admin, Developer, Security, Read-Only, or a custom role.
  3. Users in multiple mapped Groups get the union of permissions.

For the Context layer for employees setup, you can also map IdP Groups to Tool Packs.

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. For the Context layer for employees setup, 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: at Settings → Provisioning, 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.