Set up SCIM with any identity provider

HelpDocs supports SCIM 2.0, so you can connect any identity provider (IdP) that can provision users over SCIM. That includes JumpCloud, OneLogin, Ping Identity, and Rippling. See Provision users with SCIM first.

There are separate guides for Okta and Microsoft Entra ID. Google Workspace isn't supported yet.

What you need

Setting	Value
Base URL	`https://api.helpdocs.io/scim/v2`
Authentication	Bearer token in the `Authorization` header
Token	A SCIM token from HelpDocs. It starts with `hd_scim_`.
Unique user identifier	`userName`, which must be the person's email address

Your IdP may call the base URL the "SCIM base URL", "SCIM connector URL", or "Tenant URL". It may call the token an "API token", "Bearer token", or "Secret token".

Every IdP labels these fields differently. Use the closest match in your IdP's SCIM app settings.

Set it up

In HelpDocs, go to Settings > Sign-in & access.

In the SCIM provisioning section, select Create token.

Enter a Name, such as the name of your IdP, and select Create token.

In Copy your SCIM token, select Copy.

You won't see this token again.

Select Done.

Copy the SCIM base URL.

In your IdP, create or open your HelpDocs app and turn on SCIM provisioning.

Paste the base URL and token into your IdP.

Set the IdP to send the person's email address as userName.

Turn on creating users, updating users, deactivating users, and pushing groups, if your IdP offers them.

Leave password sync off. HelpDocs members sign in with SSO.

Test the connection, then assign people and groups to the app.

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

Endpoints

All paths are relative to the base URL. Every request needs a valid token, including the discovery endpoints.

Endpoint	Methods
`/ServiceProviderConfig`	GET
`/Schemas`, `/Schemas/{id}`	GET
`/ResourceTypes`, `/ResourceTypes/{id}`	GET
`/Users`	GET, POST
`/Users/{id}`	GET, PUT, PATCH, DELETE
`/Groups`	GET, POST
`/Groups/{id}`	GET, PUT, PATCH, DELETE

Responses use Content-Type: application/scim+json. Requests can use application/scim+json or application/json.

User attributes

Show the user attribute reference

Attribute	Notes
`id`	The HelpDocs user ID. Read only.
`userName`	Required. The person's email address.
`externalId`	Optional. Your IdP's ID for the person. Unique in your account.
`name.givenName`, `name.familyName`	Optional.
`displayName`	Optional. Used as the person's name in HelpDocs. If it's missing, HelpDocs uses the given and family names.
`emails`	Read only in practice. HelpDocs always returns the `userName` address as the one work email, and ignores `emails` on writes.
`active`	`false` deactivates the person. `true` reactivates them.
`groups`	Read only. The person's SCIM groups.

HelpDocs ignores other attributes and extensions.

Group attributes

Show the group attribute reference

Attribute	Notes
`id`	The HelpDocs group ID. Read only.
`displayName`	Required. 1 to 255 characters. It can't be `[Public]`.
`externalId`	Optional. Unique in your account.
`members`	`value` is a HelpDocs user ID. `display` is their email address.

Every member must already be a member, or a deactivated member, of your HelpDocs account. Create the users first.

Group members get full access to the group in HelpDocs.

Linked groups

An admin can link an existing HelpDocs group to a group name before your IdP sends it. See Link existing groups.

When a POST /Groups has a displayName that matches a link, ignoring case, HelpDocs doesn't create a new group. It takes over the linked group and returns its existing id with a 201.
The group is renamed to the displayName, and its members are replaced with the members you send. HelpDocs staff stay.
If the request fails, the link and the group stay as they were.
A DELETE /Groups/{id} on a linked group removes all its members but keeps the group in HelpDocs, so its article permissions stay. It no longer shows in SCIM.

A displayName that matches no link creates a new group, even if a HelpDocs group with that name already exists.

Filters

HelpDocs supports eq filters only, with one condition. and, or, and other operators aren't supported.

Resource	Filter attribute	Matching
Users	`userName`	Not case sensitive
Users	`emails.value`	Not case sensitive
Users	`externalId`	Exact
Groups	`displayName`	Not case sensitive
Groups	`externalId`	Exact

For example: GET /Users?filter=userName eq "sam@example.com".

Groups also accept excludedAttributes=members, which leaves members out of the response.

Paging

Use startIndex and count. startIndex starts at 1. count is 100 by default and can't be more than 100.

Updating with PATCH

PATCH is supported for users and groups, with add, remove, and replace operations.

For users, PATCH returns 200 with the updated user.
For groups, PATCH returns 204 with no body.
If any operation in a PATCH fails, nothing changes.

For users you can patch userName, externalId, displayName, name.givenName, name.familyName, and active. Paths can include the User schema URN or leave it out.

For groups you can add, remove, and replace members, and replace displayName and externalId. To remove one member, use the path members[value eq "<user id>"].

PUT replaces the attributes it includes and leaves the others as they are. A PUT without active never reactivates anyone.

What isn't supported

Bulk operations (/Bulk)
ETags and versions
Sorting
Password changes
Filters other than those listed above

Rate limit

Your account can make up to 600 SCIM requests a minute. This limit is shared by all of your account's tokens. Over the limit, HelpDocs returns 429 with a Retry-After header. Most IdPs wait and retry on their own.

Errors

Errors use the SCIM error format:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "401",
  "detail": "Invalid or missing SCIM token."
}

Status	When
`400`	The request isn't valid. `scimType` says why: `invalidSyntax` (bad JSON), `invalidFilter` (an unsupported filter), or `invalidValue` (for example, a `userName` that isn't an email address).
`401`	The token is missing, wrong, rotated, or revoked.
`403`	SCIM isn't enabled for your account, your account is inactive, you've reached your user limit, or the change isn't allowed. The `detail` says which.
`404`	The user or group doesn't exist in your account.
`409`	`scimType` is `uniqueness`. The user, email address, or `externalId` is already in use.
`429`	You've hit the rate limit.

Some changes are always refused with a 403:

Deactivating or removing the account owner, or changing their email address.
Changing HelpDocs staff.
Adding or reactivating someone when your account is at its user limit.
Changing the email address of someone who also belongs to HelpDocs accounts outside your organization, or whose HelpDocs login SCIM didn't create.
Adding someone, or changing someone's email address, when the address doesn't match the account's Email domains.

While your account is inactive, every SCIM request is refused. While editing is locked on your account, your IdP can read users but can't change them.

A request that changes nothing doesn't write anything or add to your Audit log.