---
title: "Set up SCIM with Okta"
description: "Connect Okta to HelpDocs with SCIM so Okta creates, updates, and deactivates your HelpDocs members and pushes groups. Step-by-step setup and troubleshooting."
url: "https://support.helpdocs.io/article/der7ry5xud-set-up-scim-with-okta"
category: "SCIM"
updated_at: "2026-11-12T16:15:47Z"
---

# Set up SCIM with Okta

Connect Okta to HelpDocs so Okta adds, updates, and removes your HelpDocs members and groups. See [Provision users with SCIM](/article/mboz67jrh5-provision-users-with-scim) first.

### Before you start

- SCIM provisioning is switched on for your HelpDocs account. If you can't see the **SCIM provisioning** section in **Settings > Sign-in & access**, get in touch with us in-app.
- You can edit settings in HelpDocs.
- You're an Okta admin.
- You have a HelpDocs app in Okta, usually the one you already use for SSO. Okta doesn't support SCIM on OIDC integrations created in its Classic experience, so use a SAML or SWA one.

Once you create a SCIM token, SSO and Slack sign-in stop creating new members. Have Okta ready to provision people before you create the token.

### Step 1: Create a SCIM token in HelpDocs

1

Go to **Settings > Sign-in & access**.

2

In the **SCIM provisioning** section, select **Create token**.

3

Enter a **Name**, such as "Okta", and select **Create token**.

4

In **Copy your SCIM token**, select **Copy**.

You won't see this token again, so paste it somewhere safe or keep this window open.

5

Select **Done**.

6

Copy the **SCIM base URL** with its **Copy** button. It's `https://api.helpdocs.io/scim/v2`.

### Step 2: Turn on SCIM provisioning in Okta

1

In the Okta Admin Console, open your HelpDocs app.

2

On the **General** tab, edit **App Settings** and set **Provisioning** to **SCIM**. Save.

Okta's labels for this step vary between app types and Okta versions. If you don't see a **Provisioning** option, check Okta's guide to adding SCIM provisioning to an app integration.

### Step 3: Connect Okta to HelpDocs

1

Open the **Provisioning** tab and select **Integration**, then **Edit**.

2

Fill in these settings:

| Okta setting                      | Value                                                             |
|-----------------------------------|-------------------------------------------------------------------|
| SCIM connector base URL           | Your **SCIM base URL** from HelpDocs                              |
| Unique identifier field for users | `userName`                                                        |
| Supported provisioning actions    | **Push New Users**, **Push Profile Updates**, and **Push Groups** |
| Authentication Mode               | **HTTP Header**                                                   |
| Authorization                     | The SCIM token you copied                                         |

3

Select **Test Connector Configuration**, then **Save**.

`userName` must be the person's email address. HelpDocs refuses a user whose `userName` isn't an email.

Okta sends the app username as `userName`. Where you set the app username format depends on your app type. Make sure it's the person's email address.

You can also turn on **Import New Users and Profile Updates** if you want Okta to read your existing HelpDocs members.

The exact Okta field labels may differ slightly from the ones above.

### Step 4: Choose what Okta changes

1

On the **Provisioning** tab, select **To App**, then **Edit**.

2

Turn on:

- **Create Users**
- **Update User Attributes**
- **Deactivate Users**

3

Leave **Sync Password** off. HelpDocs members sign in with SSO.

4

Save.

When Okta deactivates someone, HelpDocs deactivates them too and remembers their role and groups. See [What happens when someone is deactivated](/article/mboz67jrh5-provision-users-with-scim#what-happens-when-someone-is-deactivated).

### Step 5: Assign people and push groups

1

On the **Assignments** tab, assign the people or groups who should be HelpDocs members. Okta creates them in HelpDocs. People who are already members are matched by email.

2

On the **Push Groups** tab, push the groups you want in HelpDocs.

Pushed groups show in **Settings > Sign-in & access** under **Group roles**. Pick a role for each one. See [Give SCIM groups a role](/article/q4jncgqsm0-give-scim-groups-a-role).

If your articles already use a HelpDocs group for permissions and you want an Okta group to take it over, link them **before** you push the group. Use **Link a group** under **Link existing groups** in the **SCIM provisioning** section. When Okta first sends the group, HelpDocs renames your group to Okta's name and replaces its members with Okta's list, so people added by hand are removed. See [Link existing groups](/article/q4jncgqsm0-give-scim-groups-a-role#link-existing-groups).

In Okta, a pushed group and a group used for assignments are set up separately. Pushing a group doesn't assign its members to the app. Assign them too.

### Step 6: Check it worked

1

In HelpDocs, go to **Settings > People**. People Okta manages have a **Managed** badge.

2

In **Settings > Sign-in & access**, **Last sync** shows when Okta last used the token.

3

Your Audit log shows each change as **SCIM: Okta**, or whatever you named the token.

### Troubleshooting

401 errors

The token is wrong, rotated, or revoked. Create a new one and paste it into Okta.

403 "SCIM is not enabled for this account."

SCIM provisioning isn't switched on for your account. Get in touch with us in-app to have it switched on.

403 about the user limit

Your HelpDocs account is full. Remove a member or upgrade, then retry in Okta.

HelpDocs says "Managed by your identity provider"

The member or group is managed by Okta. Make the change in Okta.

A rename doesn't come through

Either the person also belongs to HelpDocs accounts outside your organization, or SCIM didn't create their HelpDocs login. In both cases, SCIM can't change their email.