SCIM API

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.

​

Overview

• Definitions, Overview, Concepts, and Requirements: RFC 7642
• Core Schema: RFC 7643
• Protocol: RFC 7644

​

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

​

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

​

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.

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

​

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

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

​

Create and link user groups from Okta

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

​

Automate and manage provisioning with Microsoft Entra ID

​

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

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

​

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

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