--- title: "Set up SCIM with any identity provider" description: "Connect any SCIM 2.0 identity provider, such as JumpCloud, OneLogin, or Rippling, to HelpDocs. Base URL, token, endpoints, attributes, filters, and errors." url: "https://support.helpdocs.io/article/emdrjnmprp-set-up-scim-with-any-identity-provider" category: "SCIM" updated_at: "2026-11-12T16:14:58Z" --- # 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](/article/mboz67jrh5-provision-users-with-scim) first. There are separate guides for [Okta](/article/der7ry5xud-set-up-scim-with-okta) and [Microsoft Entra ID](/article/1rlz3n199u-set-up-scim-with-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 1 In HelpDocs, go to **Settings > Sign-in & access**. 2 In the **SCIM provisioning** section, select **Create token**. 3 Enter a **Name**, such as the name of your IdP, and select **Create token**. 4 In **Copy your SCIM token**, select **Copy**. You won't see this token again. 5 Select **Done**. 6 Copy the **SCIM base URL**. 7 In your IdP, create or open your HelpDocs app and turn on SCIM provisioning. 8 Paste the base URL and token into your IdP. 9 Set the IdP to send the person's email address as `userName`. 10 Turn on creating users, updating users, deactivating users, and pushing groups, if your IdP offers them. 11 Leave password sync off. HelpDocs members sign in with SSO. 12 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](/article/q4jncgqsm0-give-scim-groups-a-role#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 ""]`. 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: ```json { "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.