Automating user and group management with SCIM – BetterUp

BetterUp supports automated user and group management through SCIM 2.0, the provisioning standard your identity provider already uses across your application portfolio. Any identity provider that implements SCIM 2.0 can connect.

With SCIM connected, your IdP becomes the source of truth for who has a BetterUp account, what their profile says, what role(s) within the BetterUp platform they hold, and which BetterUp program they are placed in. You stop maintaining that list by hand.

Availability

SCIM provisioning is enabled on a per-organization basis by BetterUp. Talk to your BetterUp account team before you begin configuration in your identity provider. Once it is enabled on your account, the configuration described below is self-service.

For your IT team: the full SCIM 2.0 specification is available at api.betterup.co/docs/scim/spec.

What SCIM does today

Accounts

Creates a BetterUp account when you assign someone the BetterUp application in your IdP.
Updates their profile when your directory changes: name, work email(s), job title.
Deactivates the account when you unassign or offboard them.
Reactivates a previously deactivated account, with the member’s history intact.

Groups

Creates and updates groups from your IdP and keeps their membership in sync.
Grants and revokes BetterUp role(s) based on group membership, so access follows your IdP instead of someone clicking through an admin panel.
Places members in a BetterUp program based on group membership, applied when they join the group and revoked when they leave.

Multiple groups can be layered and managed via SCIM (i.e., if your organization has Grow and Manage). If a member belongs to more than one base-assigning group, you set which group takes precedence.

Group changes flow through. Moving someone between groups updates their role and program; removing them revokes both.

Timing and error behavior to expect

Account creation and updates are applied when your IdP makes the call. Role and program assignment are applied shortly afterward, in the background.

If a role or program assignment fails, the provisioning call itself still succeeds. The member exists in BetterUp, and the assignment is retried automatically, but for a period they may not have the role or program you expect. If a member is missing access shortly after being added to a group, wait and re-check before escalating.

Before you map groups to programs: seat-based products

Group-driven program assignment is built for Enterprise Flex agreements, where provisioning a member does not draw from a fixed, pre-purchased seat count. In that model the number of assignments flexes with your provisioned population and automatic assignment is safe.

If your agreement is seat-based, we recommend one of our other provisioning methods. Because assignment applies to every member of a mapped group, it can allocate more members than you have seats for, or consume seats in an order you did not intend. There is currently no seat-limit enforcement in this flow. Use group-to-role mapping for admin access, and continue assigning seat-based programs through your existing process.

What SCIM does not do

It does not delete personal data. Deactivation preserves the member record so the account can be reactivated.
It does not notify you of provisioning events. There are no webhooks or event callbacks.
Groups you create in BetterUp do not sync to your IdP. Groups must originate in your IdP.

Using SCIM alongside your HCM feed

Many customers who connect SCIM also send BetterUp organizational data through their HCM or SFTP. Turning on SCIM does not replace that feed and the two are not redundant.

Your identity provider knows who someone is and which groups they belong to. Your HCM system knows their employment status and what they are eligible for. SCIM drives account lifecycle and access. Your HCM feed drives eligibility and license changes. Program configuration is scoped to the provisioning source it came from, so enabling SCIM does not change how your existing file-based provisioning behaves.

Attributes BetterUp reads

BetterUp implements the SCIM 2.0 core schemas for users and groups, aligned to RFC 7643 and RFC 7644. Attributes outside these lists are ignored rather than rejected, so extra mappings in your IdP will not break your sync.

Users · /scim/v2/Users

Attribute	Mutability	Notes
id	Read-only	Server-assigned, immutable BetterUp identifier
externalId	Read/write	Correlates your IdP user to the BetterUp user
userName	Read/write	Required. Must be the member’s primary email address
name.givenName	Read/write	First name
name.familyName	Read/write	Last name
emails[].value	Read/write	Primary mirrors userName; a type=other entry can carry an alternate
active	Read/write	false deactivates, true reactivates. DELETE has the same effect
title	Read/write	Job title
meta.*	Read-only	resourceType, created, lastModified, location

Groups · /scim/v2/Groups

Attribute	Mutability	Notes
id	Read-only	Server-assigned, immutable group identifier
externalId	Read/write	Also the idempotency key for POST within an organization
displayName	Read/write	Required. Does not need to be unique in your organization
members[].value	Read/write	The id of a SCIM-provisioned member in the same organization
members[].type	Read/write	User only. Nested groups are not supported
meta.*	Read-only	resourceType, created, lastModified, location

Setting up SCIM

Once SCIM is enabled on your account and you’ve set up SSO in your IdP:

In your partner admin settings, create an API credential and select the SCIM scopes you need. Authentication uses the OAuth 2.0 client credentials grant. Available scopes are scim:user:read, scim:user:write, scim:group:read, and scim:group:write. Grant only what your connector requires, and set an expiry if your security policy expects one.

In your identity provider, enable SCIM provisioning and configure the BetterUp application for importing and pushing users and groups with the SCIM base URL and your client credentials.

Enable create, update, and deactivate operations in your IdP, and assign a small pilot group first.

In BetterUp under Organization Settings, verify the pilot members appear correctly before assigning the application more broadly. This process can take several minutes.

Open the SCIM Group to map groups to role(s) and programs

The SCIM Groups page lists each provisioned group with its member count and mapping count. Opening a group shows its members and its mappings, and lets you add or remove them.

Troubleshooting

A member was provisioned but cannot sign in. SCIM creates the account; your IdP still authenticates the member. Confirm SSO and SCIM point at the same identity.

Adding a member to a group returns a 400. Every member id in the request must belong to a member already provisioned to BetterUp in the same organization. An unresolved id fails the whole call. Provision members before adding them to groups (most IdPs will handle this for you).

A nested group did not sync. Nested groups are not supported. Only individual members can belong to a BetterUp group, so flatten group hierarchies in your IdP before pushing them.

A group was created twice. BetterUp uses externalId to recognize a group it has already seen, so make sure your IdP sends a stable externalId. Group display names are not required to be unique and are not used for matching.

A role or program did not appear. These are applied in the background and retried on failure. Allow time before escalating.

A previously deactivated member is not reactivating cleanly. Confirm your IdP is sending active: true on the existing record rather than attempting to create a new one.