> For the complete documentation index, see [llms.txt](https://help.dscout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dscout.com/account-management/user-management-and-security/user-provisioning-scim.md).
# User provisioning (SCIM)
{% hint style="info" %}
**Note:** This feature is only available on **Enterprise** plans.
{% endhint %}
Customers using [Single Sign-on](/account-management/user-management-and-security/sso-okta-integration.md) also have access to user provisioning & de-provisioning via Dscout's implementation of industry standard SCIM API. This feature allows customers to use their identity provider (IdP) to securely create Dscout accounts for their users, keep their information (name, email, etc.) in sync, and revoke access to Dscout (de-provision) .
Your Dscout account owner and/or IdP administrator will manage access to Dscout. When your Dscout account is ready, they will provide login instructions.
{% hint style="success" %}
***If you're using Okta, refer to*** [***this guide***](/account-management/user-management-and-security/user-provisioning-scim/dscout-okta-scim-integration.md)***.*** If you're not using Okta, read on.
{% endhint %}
### Generating an API key
Dscout account owners may generate an API key on the Dscout [settings page](/account-management/organization-account-settings/manage-organization-account-settings.md). Upon clicking “Generate API key” you will be prompted to name your key. You may then work with your organization’s IdP administrator to enter this key into your IdP’s authentication configuration for your Dscout connection.
### Using user provisioning (SCIM) exclusively
Once your API key is generated and you’ve successfully connected your identity provider to Dscout, we strongly recommend toggling this setting *on* to only allow users to be managed via user provisioning (SCIM). Once this setting is on, you will no longer be able to add or remove users from the platform without first provisioning or de-provisioning them in your IdP.
### What to do after provisioning
Users that are provisioned will be added to Dscout as a **viewer**. Inside Dscout you can choose the right [role](/getting-started/dscout-quickstart-guide/user-roles-and-permissions.md) for new users by going to the [Users page](/getting-started/dscout-quickstart-guide/user-roles-and-permissions.md) in account management. Additionally, you can add users to projects using either the **“add users to projects”** button on the [projects page](/account-management/organization-account-settings/manage-organization-account-settings.md) or using the [“Add collaborators” button](/getting-started/collaborate-in-dscout/manage-project-collaborators.md) directly on the project.
### API features
Dscout's SCIM API is based on the Open standard: System for Cross-domain Identity Management 2. Our implementation uses version 2.0 of the protocol. The API has been tested against Okta, OneLogin and Microsoft Entra ID (formerly named Azure Active Directory) and should work with any identity provider using the SCIM protocol.
### Base URL and authentication
The API’s base URL is `https://app.dscout.com/scim/v2`. It expects the generated key to be provided in the requests header as a Bearer token.
```
# Curl example curl --request GET \ --url https://app.dscout.com/scim/v2/Users \--header 'Authorization: Bearer YOUR_API_KEY'
```
### Supported resources and attribute mapping
**Users**
User attributes should be mapped as follows:
| SCIM attribute | External namespace | Suggested mapping | Description |
| -------------- | -------------------------------------------- | ----------------- | --------------------------------------------- |
| `userName` | `urn:ietf:params:scim:schemas:core:2.0:User` | `user.email` | Mandatory. Maps to Dscout's user email. |
| `givenName` | `urn:ietf:params:scim:schemas:core:2.0:User` | `name.givenName` | Mandatory. Maps to dscout’s user first name. |
| `familyName` | `urn:ietf:params:scim:schemas:core:2.0:User` | `name.familyName` | Mandatory. Maps to Dscout's user last name. |
| `title` | `urn:ietf:params:scim:schemas:core:2.0:User` | `title` | Recommended. Maps to Dscout's user job title. |
| `timezone` | `urn:ietf:params:scim:schemas:core:2.0:User` | `timezone` | Recommended. Maps to Dscout's user time zone. |
Dscout's API supports the following actions for users:
* List all provisioned users
* Create a new user
* Get a user by ID
* Replace user by ID
* Update user attribute by ID
Please note the absence of a delete user action. When it is time to revoke Dscout access for a user, our API expects SCIM clients to send a PUT or PATCH request with `active=false`. This action will make the user as deactivated, convert them to a free “viewer” seat and prevent them from logging into the platform. Additionally, your account manager can then choose to delete their record from [user management in the account settings.](/account-management/organization-account-settings/manage-organization-account-settings.md)
### Special callouts for specific identity providers
**Microsoft Azure Entra ID**
Microsoft has [documented several known issues](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility) with their compliance against the SCIM 2.0 specification. Dscout requires the addition of the their recommended query parameter\
(`?aadOptscim062020`) in order for your integration to work properly. Your tenet URL should read as follows:
```
https://app.dscout.com/scim/v2?aadOptscim062020
```
### Groups
Group attributes should be mapped as follows:
| SCIM attribute | External namespace | Suggested mapping | Description |
| -------------- | --------------------------------------------- | ----------------- | --------------------------- |
| `displayName` | `urn:ietf:params:scim:schemas:core:2.0:Group` | `displayName` | Mandatory. The team’s name. |
| `members` | `urn:ietf:params:scim:schemas:core:2.0:Group` | `members` | List of the team's members. |
Dscout’s API supports the following actions for groups:
* List all groups
* Create a new group
* Get a group by ID
* Replace group by ID
* Update group by ID
* Add, remove, or replace group members by group ID
* Delete a group by ID
The primary use case for SCIM groups in Dscout is mapping group members to a specific role. When you create groups via SCIM, you’ll see them beneath your SCIM API key configuration. By default, all groups map to Dscout's “viewer” role. Optionally, you can change these mappings to other seat types. Now, when one of your users is added to that group, their role will update to the group’s specified role mapping.
A few callouts about groups, group members and role mappings:
* You can always override a user’s role by changing their role on the user’s page of account management.
* Dscout define’s the role hierarchy as Admin (highest), Researcher, Contributor, Viewer (lowest).
* Dscout’s API will never downgrade a user’s role. For example, if a user has an Admin role and is then added to a group with a Viewer mapping, they will continue to be an Admin.
* Conversely, Dscout’s API will upgrade a user’s role. For example, if a user has a Viewer role and is added to a group with an Admin mapping, their role will change to Admin.
* The account owner’s role will never change.
* Once your account has exhausted its purchased seats for a certain type, users will mapped to Viewer role.
### FAQs
After enabled SCIM, will all of my current users assigned to the application be migrated to Dscout?
No. Only users updated or added after SCIM is enabled are added.
I’m an existing customer and have already added many users in Dscout. How do I sync them with my identity provider?
In your identity provider, simply assign all relevant users to Dscout. If the user does not already exist in Dscout, their account will be provisioned. If the user was previously added manually in Dscout, this process with sync those records (please confirm that user’s email in your identity provider matches the user’s email on their existing Dscout account).
Will newly provisioned users receive a notification or invite from Dscout?
No. Dscout will not notify new users upon provisioning. We leave their notification in your hands after you’ve made any necessary adjustments to their role and/or added them to any workspaces or projects.
I deprovisioned a user from Dscout in my identity provider, but they are still showing up in Dscout.
Our SCIM API accepts “deactivation” requests from your identity provider, but we do not delete the user from your account. Instead, we mark them as “deprovisioned” and disallow the user from accessing Dscout. You (or your account owner) can login to Dscout once the user is deactivated and remove them.
How can I learn more about SCIM?
There are many good references on the internet. Here are a few:
* [Overview of SCIM](http://www.simplecloud.info/)
* [Understanding SCIM - Okta](https://developer.okta.com/docs/concepts/scim/)
* [SCIM: Core Schema](https://datatracker.ietf.org/doc/html/rfc7643)
* [SCIM: Protocol](https://datatracker.ietf.org/doc/html/rfc7644)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.dscout.com/account-management/user-management-and-security/user-provisioning-scim.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.