1. Betterworks
  2. Betterworks
  3. NextGen

SCIM User Provisioning - Okta (NextGen)

Contents

Overview
Requirements
Generating your Betterworks API token
Setup Instructions
User deactivation and reactivation
Limitations
Troubleshooting
 

Overview

Betterworks supports System for Cross-domain Identity Management (SCIM) 2.0, allowing organizations to automate user provisioning through their identity provider (IdP).

By integrating Okta with Betterworks, administrators can automatically create, update, and deactivate user accounts based on changes made in Okta. This reduces the need for manual user management and helps keep employee information consistent across both systems.


Requirements

To configure SCIM 2.0 provisioning with Okta, you will need:

  • Betterworks Super Admin access to generate an API token.
  • Okta administrator access to configure the integration.
  • Your organization's Betterworks environment URL (e.g. https://app.betterworks.com).


Generating your Betterworks API token

  1. Log in to Betterworks as a Super Admin.
  2. Navigate to User Admin → Integrations → Betterworks API.
  3. Generate an API key to use when configuring the SCIM connection in Okta.
  4. Store the key securely, as it will be required during setup.

Note: The API token carries Super Admin-level permissions and is not restricted to SCIM operations. Treat it as a sensitive administrator credential and ensure it is stored securely.


Setup Instructions

Step 1: Add the SCIM application

  1. Log in to the Okta Admin Console.
  2. Navigate to Applications → Applications → Browse App Catalog.
  3. Search for SCIM.
  4. Select SCIM 2.0 Test App (Header Auth).
  5. Click Add Integration.
image-20260828-000513.png
image-20260828-000559.png

 

Step 2: Configure general settings

  1. Enter a recognizable application name, such as Betterworks SCIM 2.0.
  2. Continue to the next step.
image-20260828-000413.png

 

Step 3: Configure sign-on options

  1. Select Secure Web Authentication (SWA).
  2. Choose User sets username and password.

  3. In the Login URL field, enter your organization's Betterworks login URL, for example:

    https://app.betterworks.com/app/#/login

  4. Leave any SAML-specific fields, such as ACS URL or Audience URI, blank.
  5. Continue to complete the application setup.

Note: SCIM provisioning does not manage user authentication. The sign-on configuration above is used for application setup and does not replace your organization's existing Betterworks authentication method.

image-20260828-000736.png
image-20260828-000857.png

 

Step 4: Configure the SCIM connection

  1. Open the newly created application's Provisioning tab.
  2. Select Configure API Integration.
  3. Enable API Integration.
  4. Complete the following fields:
Field Value
Base URL Your Betterworks environment URL followed by /scim/v2
API Token Your Betterworks API token, preceded by Bearer and a space
Import Groups Leave unchecked

Example Base URL:

https://app.betterworks.com/scim/v2

Example API Token format:

Bearer <your-api-token>

Ensure that the word Bearer and a space are included before your token.

  1. Click Test API Credentials to verify the connection.
  2. Once the connection is successful, click Save.

Note: Group and department provisioning is not supported through SCIM. Ensure that Import Groups remains unchecked.

image-20260828-001220.png

 

 

Step 5: Configure attribute mappings

The attribute mappings determine which employee information is synchronized from Okta to Betterworks.

Configure the mappings to include only the attributes supported by Betterworks.

 

image-20260828-001343.png

 

The supported user attributes are synchronized when users are created and updated. Changes made to these attributes in Okta will automatically update the corresponding information in Betterworks.

All other default field (middle name, nickname, phone, address, locale, timezone, department, cost center, employee number, etc.) can be safely deleted from the mapping.

 

Step 6: Enable provisioning actions

Under Provisioning → To App, configure the following settings:

image-20260828-001413.png

Leave Sync Password disabled, as SCIM provisioning does not manage user passwords or authentication.

 

Step 7: Assign users

Please Note: We recommend starting off by assigning a small group of users to verify that provisioning works as expected before expanding to the rest of your organization.

Once the SCIM connection and attribute mappings have been configured, users can be assigned to the Betterworks application in Okta.

  1. In the Okta Admin Console, navigate to Applications → Applications.
  2. Select the Betterworks SCIM 2.0 application created during setup.
  3. Open the Assignments tab.
  4. Click Assign and select Assign to People.
  5. Find the users you want to provision and click Assign next to each user.
  6. Complete any required assignment fields, then click Save and Go Back.
  7. Once all users have been selected, click Done.
  8. Verify that the users have been successfully provisioned in Betterworks.

If users already exist in Betterworks, SCIM provisioning will match them to their existing accounts using their email addresses, provided the email addresses match exactly. This prevents duplicate accounts from being created.

 

User deactivation and reactivation

Deactivating users

When a user is deactivated in Okta or unassigned from the Betterworks SCIM application, their Betterworks account is automatically deactivated.

No additional action is required in Betterworks.

Reactivating users

Reactivating a user in Okta does not automatically reactivate their Betterworks account.

To reactivate a user in Betterworks:

  1. Open the Betterworks SCIM application in Okta.
  2. Navigate to the Assignments tab.
  3. Reassign the user to the application, or select Provision User if the assignment already exists.
  4. Allow the provisioning action to complete and verify that the account is active in Betterworks.

 

Limitations

The following limitations apply to Betterworks SCIM 2.0 provisioning:

  • Groups and departments: Group and department provisioning is not supported.
  • Manager relationships: Manager information cannot be synchronized through SCIM.
  • Additional employee attributes: Fields such as employee number, hire date, and custom fields are not supported.
  • Bulk operations: SCIM bulk operations are not supported.
  • Password synchronization: SCIM cannot be used to synchronize user passwords.
  • SCIM /Me endpoint: This endpoint is not supported.
  • HRIS integrations: SCIM provisioning and Betterworks HRIS Integrations cannot be used simultaneously within the same organization. Existing HRIS Integrations must be disabled before enabling SCIM provisioning.

 

Troubleshooting

If you encounter issues when configuring or using SCIM provisioning, review the following.

API connection fails

If the API credentials test is unsuccessful:

  • Confirm that the Betterworks API token is valid.
  • Verify that the Base URL matches your organization's Betterworks environment.

A user fails to provision

If an individual user cannot be provisioned:

  • Confirm that the user is assigned to the Betterworks SCIM application in Okta.
  • Verify that the user's email address is correct.
  • Ensure that the user's Title field is populated in Okta.
  • Review the user's provisioning error in the application's Assignments tab.

Reviewing provisioning logs

Okta provides logs to help identify provisioning errors.

  1. Open the Betterworks SCIM application in Okta.
  2. Navigate to the Assignments tab to review individual user provisioning errors.
  3. Select View Logs to access the Okta System Log for additional details about provisioning activity and errors.

If the issue persists, contact Betterworks Support with the relevant error message and details of the impacted user.