> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dovetail.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM API

<Info>
  Available on **Enterprise plan**
</Info>

## Overview

When SCIM is provisioned with your identity provider, users in your workspace can be automatically provisioned, managed, and deactivated.

**Note:** Dovetail implements SCIM 2.0 as specified in the RFC documents from the Internet Engineering Task Force:

* [Definitions, Overview, Concepts, and Requirements: RFC 7642](https://tools.ietf.org/html/rfc7642)
* [Core Schema: RFC 7643](https://tools.ietf.org/html/rfc7643)
* [Protocol: RFC 7644](https://tools.ietf.org/html/rfc7644)

<Note>
  We currently support only Okta and Entra ID SCIM, but we’re working to add more identity providers soon.
</Note>

***

## What can you do with Dovetail's SCIM API

* **Push New Users →** New users created through your identity provider will also be created in Dovetail.
* **Push Profile Updates →** Updates made to the user’s profile through your identity provider will be pushed to Dovetail.
* **Push New Groups →** New user groups created through your identity provider will also be created in Dovetail.
* **Push User Deactivation →** Deactivating the user or deleting the user will deactivate the user in Dovetail.
* **Reactivate Users →** Reactivated users are also reactivated in Dovetail.

***

## Users

### User attributes

All attributes are in the "urn:ietf:params:scim:schemas:core:2.0:User" namespace

| Attribute       | SCIM namespace                                           | SCIM attribute | Type                                   | Required | Description                                                                                            |
| :-------------- | :------------------------------------------------------- | :------------- | :------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------- |
| Email           | urn:ietf:params:scim:schemas:core:2.0:User               | userName       | email                                  | yes      | User email                                                                                             |
| Active          | urn:ietf:params:scim:schemas:core:2.0:User               | active         | boolean                                | yes      | Determines whether or not this user can log in to Dovetail                                             |
| Full name       | urn:ietf:params:scim:schemas:core:2.0:User               | displayName    | string (max length 100 characters)     | no       | Name displayed in Dovetail                                                                             |
| Role            | urn:ietf:params:scim:schemas:core:2.0:User               | role           | “MANAGER” or “CONTRIBUTOR” or “VIEWER” | no       | Sets the [Dovetail role](https://docs.dovetail.com/help/user-roles/#user-roles-for-enterprise)         |
| Workspace admin | urn:ietf:params:scim:schemas:extension:dovetail:2.0:User | workspaceAdmin | boolean                                | no       | Set [Dovetail workspace admin](https://docs.dovetail.com/help/user-roles/#grant-admin-access-to-users) |

### User methods

* **GET /Users**
  * Returns a paginated list of users.
  * You can paginate using the **startIndex** and **count** parameters.
  * You can filter results with the **filter** parameter. Valid attributes to filter are **displayName** and **userName** using **eq** and **and**.
* **POST /Users**
  * Create a new user in your workspace.
  * Required attributes are **userName** and **active**.

***

## **Groups**

### **Group attributes**

| Attribute | SCIM namespace                              | SCIM attribute | Description                          |
| :-------- | :------------------------------------------ | :------------- | :----------------------------------- |
| Name      | urn:ietf:params:scim:schemas:core:2.0:Group | displayName    | Name of the user group. Required     |
| Members   | urn:ietf:params:scim:schemas:core:2.0:Group | members        | List of Dovetail users in the group. |

### Group methods

* **GET /Groups**
  * Returns a paginated list of user groups.
  * You can paginate using the **startIndex** and **count** parameters.
  * You can filter results with the **filter** parameter. Valid attributes to filter are **displayName** using **eq**.
* **POST /Groups**
  * Create a new user group in your workspace.
  * Required attributes are **displayName**.
* **PATCH /Groups/\<id>**
  * Update an existing user group.
  * We only support adding members to a group via the Dovetail user ID.

```json theme={null}


{
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:PatchOp"
	],
	"Operations": [
		{
			"op": "add",
			"path": "members",
			"value": [
				{
					"value": <dovetail_user_id>
				}
			]
		}
	]
}
```

***

## Automate and manage provisioning with Okta

<Warning>
  Ensure that you have configured Okta as your identity provider in your Dovetail workspace before configuring SCIM provisioning.
</Warning>

### Configure SCIM provisioning in Okta

* Open the Dovetail app you’ve set up in Okta and navigate to **Provisioning**.
* Under **Integration**, click **Configure API integration**, check **Enable API integration**, and click **Authenticate with Dovetail**. Ensure you are logged in to Dovetail as a workspace admin.
* From within the pop-up window, select your Dovetail workspace and click **Allow**. Once you are directed back to Okta, click **Save**.
* Under **To app**, click **Edit** and enable your preferred features: Create users, Update user attributes, or Deactivate users. Click **Save.**
* Navigate to the **Sign On** tab, and ensure that the **Application username format** is set to **Email**.

***

### Provision users from Okta

To provision users in Dovetail from Okta, complete these steps:

* Navigate to the **Assignments** tab.
* Click **Assign**, then **Assign to People**, or **Assign to Groups**.
* Select a user or a group, and assign a Dovetail role and **Dovetail workspace admin** from the relevant fields. Click **Save**.

Your users in Okta have now been provisioned in your Dovetail workspace. If a user is deactivated in Okta, their Dovetail account will also be deactivated and they will lose access to your workspace.

***

### Create and link user groups from Okta

<Warning>
  If you do not already have a group in Okta that you’d like to link or push to a user group in Dovetail, navigate to **Directory → Groups → Add Group**.
</Warning>

To link a user group in Dovetail with a group in Okta, complete these steps:

* Navigate to the **Push Groups** tab, select **Push Group** and enter the name of the group.
* From there, select **Push Groups**, and find your group by name, or by rule.
* If you have an existing user group in Dovetail you would like to link this group to, select Link Group and enter the name of the user group in Dovetail. If you would like to create a new user group, select **Create Group**, and click **Save**.

Your group in Okta and your user group in Dovetail are now linked. Any users you add to the group in Okta who are also assigned to your Dovetail application will be added to the group in Dovetail.

***

# Automate and manage provisioning with Microsoft Entra ID

Ensure that you have configured SAML SSO with Microsoft Entra ID as your identity provider in your Dovetail workspace before configuring SCIM provisioning. See [SAML](https://docs.dovetail.com/help/saml) if you haven't done this yet.

### Create a SCIM client in Dovetail

* In Dovetail, open the menu and go to **More → Settings → Authentication**.
* Under your Enterprise SSO connection, find the **SCIM provisioning** section and click **Create SCIM client**.
* Click **Next** to generate the credentials.
* Copy the **Client ID**, **Client secret**, **Tenant URL**, and **Token endpoint** and store them securely. The client secret is shown only once — if you lose it, you'll need to rotate the credentials.

***

### Configure App Roles in Entra ID

App Roles are how Entra ID communicates a user's Dovetail role over SCIM. You must define them before provisioning will work.

* In the Microsoft Entra admin center, go to **App registrations** and open your Dovetail application.
* Under **Manage**, select **App roles → Create app role**.
* Create one role for each Dovetail role you want to use. The **Value** field must be exactly `MANAGER`, `CONTRIBUTOR`, or `VIEWER` (uppercase).
* Enable each role and click **Apply**.

***

### Assign users and groups to roles

* In the **Enterprise applications** view of your Dovetail app, go to **Manage → Users and groups → Add user/group**.
* Pick a user or group, and under **Select a role**, choose the matching App Role.
* Click **Assign**. Repeat for each group/role pairing you need.

Note: each user can only have one role. Assign each user to exactly one App Role, either directly or through a single group.

***

### Configure SCIM provisioning in Entra ID

* In **Enterprise applications**, open your Dovetail application and go to **Manage → Provisioning**.
* Set **Provisioning Mode** to **Automatic**.
* Under **Admin Credentials**, set the **Authentication Method** to **OAuth 2.0 Client Credentials Grant** and enter the **Client ID**, **Client secret**, **Tenant URL**, and **Token endpoint** from the first step.
* Click **Test Connection** to confirm the credentials are valid, then click **Save**.

***

### Map the roles attribute

Entra ID's default mapping doesn't send role assignments in the format Dovetail expects. You need to add a custom expression mapping.

* Under **Mappings**, open **Provision Microsoft Entra ID Users** and click **Add New Mapping**.
* Set **Mapping type** to **Expression** and enter `SingleAppRoleAssignment([appRoleAssignments])` as the expression.
* Set the **Target attribute** to `roles[primary eq "True"].value` and **Apply this mapping** to **Always**.
* Click **OK**, then **Save**.

### Start provisioning

* Back on the **Provisioning** overview, set **Provisioning Status** to **On** and click **Save**.

Entra ID syncs every 40 minutes. To verify immediately, use **Provision on demand**, search for a test user assigned to one of the Dovetail App Roles, and click **Provision**. Confirm the user appears in **Settings → Users** in Dovetail with the correct role.