Configuring Okta SCIM v2.0

Learn about syncing your user list with Okta SCIM v2.0


This guide outlines how to synchronize your application's Okta directories using SCIM v2.0

To synchronize an Enterprise's users and groups provisioned for your application, you'll need to provide the Enterprise with two pieces of information:

  • An Endpoint that Okta will make requests to.
  • A Bearer token for Okta to authenticate its endpoint requests.

Both of these are available in your Endpoint's Settings in the Developer Dashboard.

Steps 2, 3, and 4 below will need to be carried out by the Enterprise when configuring your application in their Azure AD instance.

Set up your directory sync endpoint

Click "Add new endpoint".

Input your Enterprise's name, and select "Okta SCIM v2.0" from the dropdown.

Then, click "Create endpoint."

We have support for whitelabeled URLs for Directory Sync endpoints. Contact us for more info!

Configure your Okta provisioning API integration

In your application's Enterprise Okta admin panel, click the "Provisioning" tab.

Then, click "Configure API Integration" and check "Enable API Integration".

After that, copy and paste the Endpoint from your Developer Dashboard in the SCIM 2.0 Base URL field.

Then, copy and paste the Bearer Token from your Developer Dashboard into the OAuth Bearer Token field.

Click "Test API Credentials".

Click "Save".

Select options to provision to your application

In the "To App" navigation section, check to enable:

  • Create Users
  • Update User Attributes
  • Deactivate Users

Click "Save".

Assign users and groups to your application

In the "Assignments" tab, from the "Assign" dropdown, select:

"Assign to People" and then select users to provision. Press "Save and go back" and then witness realtime changes in your WorkOS Developer Dashboard.

In the "Push Groups" tab, from the "Push Groups" dropdown, select:

"Find Groups by Name" and select groups to provision. Check "Push immediately" and click "Save". Witness realtime changes in your WorkOS Developer Dashboard.

Frequently asked questions

When a user is removed from my Okta SCIM app, the dsync.user.deleted webhook isn't called - is this expected?

If a user is removed from the SCIM app in Okta, but not deleted from the Okta directory, you'll see a dsync.user.updated event. This is expected, because the user was just updated in Okta, not deleted from Okta. In this dsync.user.updated event, you should see the active attribute display as false, which is what you can programmatically use to block or delete the user in your app. You can find this active attribute in the raw_attributes of the webhook. An example Okta SCIM 2.0 webhook is displayed below:

Okta SCIM User Updated Webhook

  "event": "dsync.user.updated",
  "data": {
    "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
    "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
    "raw_attributes": {
      "id": "directory_user_01E1X56GH84T3FB41SD6PZGDBX",
      "name": {
        "givenName": "Eric",
        "familyName": "Schneider"
      "active": false,
      "emails": [
          "type": "work",
          "value": "[email protected]",
          "primary": true
      "locale": "en-US",
      "schemas": [
      "userName": "[email protected]",
      "externalId": "00u1e8mutl6wlH3lL4x7",
      "displayName": "Eric Schneider",
      "groups": []
    "first_name": "Eric",
    "emails": [
        "type": "work",
        "value": "[email protected]",
        "primary": true
    "username": "[email protected]",
    "last_name": "Schneider"
User is removed from Okta SCIM app