SCIM Management API Overview
Overview
These APIs are specifically used by external IdPs, to perform actions relating to SCIM users. For User and Group management, refer to our User Management or Group Management APIs.
Descope provides inbound SCIM (System for Cross-domain Identity Management) support, allowing your Identity Provider (IdP) to push user and group data to Descope. Descopers can configure SCIM provisioning from their IdP, which will then be able to push user profile updates as well as groups.
The Descope API then opens endpoints to load, create, update, and delete SCIM-related configurations. The Descope SDK does not support the same SCIM endpoints as the API.
Important Configuration Notes
1. Obtaining Project ID and Access Key
In the Descope console, navigate to your project settings to retrieve the ProjectId and generate an AccessKey for SCIM configuration. Ensure that the access key has tenant admin privileges and is securely stored.
2. Authentication Header Format
All SCIM API requests require a Bearer token in the following format:
3. Supported Attributes and Schema
Each SCIM resource type has specific attributes that Descope supports, such as emails, phoneNumbers, and displayName for users. Review Descope’s schema documentation to ensure the IdP attributes align with Descope’s requirements.
SCIM API Endpoints
These are a list of the all of the endpoints you will find in provided by our management service.
Base URL
All SCIM requests to Descope should be directed to the following base URL, or your custom domain if configured:
Group Management Endpoints
GET /scim/v2/Groups
Purpose: Search SCIM groups associated with the Descope application and tenant.
Description: This endpoint allows administrators to view all SCIM groups within the Descope environment, including details of their members.
Use Case: Use this endpoint to verify group memberships or synchronize group information.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
POST /scim/v2/Groups
Purpose: Create a new SCIM group.
Description: This endpoint lets administrators create new groups and specify properties such as groupId, displayName, and members.
Use Case: Use this to add groups in bulk or provision groups according to your organizational structure.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
GET /scim/v2/Groups/{groupId}
Purpose: Retrieve a specific SCIM group’s details using groupId.
Description: Fetches details of a specified group, including displayName and members.
Use Case: Retrieve precise information on a single group to manage group access or verify membership details.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
PUT /scim/v2/Groups/{groupId}
Purpose: Update an existing SCIM group’s details.
Description: Modify properties such as displayName and members by specifying the groupId.
Use Case: Adjust groups to ensure they reflect the latest structure or access needs.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
DELETE /scim/v2/Groups/{groupId}
Purpose: Delete a SCIM group using groupId.
Description: Removes the specified group from the Descope tenant.
Use Case: Clean up outdated or redundant groups to maintain an organized environment.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
PATCH /scim/v2/Groups/{groupId}
Purpose: Partially update a SCIM group’s details.
Description: Use this to modify only specific attributes of a group, such as updating its members or displayName.
Use Case: Quickly apply minor updates to a group without overwriting its full configuration.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
User Management Endpoints
GET /scim/v2/Users/{userId}
Purpose: Retrieve a specific SCIM user’s details using userId.
Description: Access detailed profile information such as email, phone, username, and other attributes.
Use Case: Check or validate user data against the IdP to ensure accurate records.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
PUT /scim/v2/Users/{userId}
Purpose: Update a SCIM user’s information.
Description: Modify user attributes, including displayName, phoneNumbers, emails, and active status.
Use Case: Keep user profiles up-to-date by synchronizing changes from the IdP.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
DELETE /scim/v2/Users/{userId}
Purpose: Delete a SCIM user.
Description: Remove a user from Descope’s environment to reflect changes in the IdP.
Use Case: Deprovision users who no longer require access.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
Metadata Endpoints
GET /scim/v2/ResourceTypes
Purpose: Retrieve available SCIM resource types.
Description: Lists the types of SCIM resources supported within Descope.
Use Case: Familiarize yourself with the resources that can be provisioned via SCIM.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
GET /scim/v2/ServiceProviderConfig
Purpose: Retrieve SCIM service provider configuration.
Description: Provides detailed information on supported configurations and schemas for SCIM provisioning.
Use Case: Use this information to align your IdP’s configuration with Descope’s requirements.
Authorization: Bearer token format: ProjectId:AccessKey, requiring tenant admin privileges.
This guide provides the foundation for configuring SCIM provisioning between Descope and your IdP, helping maintain accurate user and group data across systems. For further assistance, consult the Descope API documentation or contact support.