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 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

Go to Settings > Sign-in & access.

In the SCIM provisioning section, select Create token.

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

In Copy your SCIM token, select Copy.

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

Select Done.

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

In the Okta Admin Console, open your HelpDocs app.

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

Open the Provisioning tab and select Integration, then Edit.

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

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

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

Turn on:

Create Users
Update User Attributes
Deactivate Users

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

Save.

When Okta deactivates someone, HelpDocs deactivates them too and remembers their role and groups. See What happens when someone is deactivated.

Step 5: Assign people and push groups

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.

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.

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.

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

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

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

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.